Criar/Atualizar Ação

Criar novas ações ou atualizar ações existentes para um agente de voz. Este endpoint permite configurar webhooks, transferências de chamada, holds e outras ações que o agente pode executar durante as conversas.

Endpoint

POST /api/v1/agents/{agent_id}/actions

Parâmetros de Caminho

agent

string

obrigatório

O identificador único do agente de voz. Você pode encontrá-lo em seu painel, na seção Agentes de Voz.

Cabeçalhos da Requisição

Authorization

string

obrigatório

Token Bearer para autenticação. Formato: Bearer talq_your_environment_token_here

Content-Type

string

obrigatório

Deve ser definido como application/json

Corpo da Requisição

node_id

string

obrigatório

ID do nó da ação para integração com o fluxo de trabalho

name

string

obrigatório

Nome da ação (máximo de 255 caracteres)

description

string

obrigatório

Descrição detalhada do que a ação faz

type

string

obrigatório

Tipo da ação. Opções: webhook, transfer, hold, etc.

inputs

array

Array de parâmetros de entrada para a ação

integration

object

Objeto de configuração da integração

url

string

URL do webhook (deve ser uma URL válida — usada por ações webhook).

authorization_url

string

URL de autorização (deve ser uma URL válida — usada por ações webhook quando o destino requer um endpoint de autorização separado).

authorization_scheme

string

Esquema de autorização usado ao chamar url. Opções: none, bearer, basic, api_key, custom. Padrão: none.

custom_headers

array

Array de cabeçalhos HTTP customizados a enviar com a requisição do webhook. Cada item é { "key": "Header-Name", "value": "header-value" }.

speak_on_send

string

Frase que o agente dirá quando o webhook for acionado (antes da chamada para url). Útil para manter a conversa natural enquanto a integração é executada.

speak_on_receive

string

Frase que o agente dirá após o webhook responder com sucesso. A resposta do webhook pode ser referenciada via variáveis de template.

execution_mode

string

Define quando a ação é executada. Opções:

during_call (padrão) — webhook executa durante a conversa, a resposta é consumida pelo agente
post_call — webhook executa após o término da chamada (válido apenas para o tipo de ação external)

hold_duration

integer

Duração do hold em segundos (para ações hold).

transfer_to

string

Número de telefone de destino da transferência no formato E.164 (para ações transfer).

current_status

string

Status da ação. Opções: active, inactive. Padrão: active.

Exemplos de Requisição

# Request 1: Create webhook action
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "action-node-456",
    "name": "Schedule Meeting",
    "description": "Schedule a meeting with the customer",
    "type": "webhook",
    "inputs": [
      {
        "name": "date",
        "type": "string",
        "required": true,
        "description": "Meeting date"
      },
      {
        "name": "time",
        "type": "string",
        "required": true,
        "description": "Meeting time"
      }
    ],
    "integration": {
      "id": "integration-uuid"
    },
    "url": "https://api.example.com/schedule",
    "authorization_url": "https://api.example.com/auth",
    "current_status": "active"
  }'

# Request 2: Create transfer action
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "action-node-789",
    "name": "Transfer Call",
    "description": "Transfer the call to a human agent",
    "type": "transfer",
    "inputs": [
      {
        "name": "transfer_to",
        "type": "string",
        "required": true,
        "description": "Transfer to",
        "value": "+1234567890"
      }
    ],
    "transfer_to": "+1234567890",
    "current_status": "active"
  }'

# Request 3: Create hold action
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "action-node-101",
    "name": "Put Call on Hold",
    "description": "Put the current call on hold for a specified duration",
    "type": "hold",
    "inputs": [
      {
        "name": "hold_duration",
        "type": "integer",
        "required": true,
        "description": "Hold duration in seconds",
        "value": 30
      }
    ],
    "hold_duration": 30,
    "current_status": "active"
  }'

Resposta

Resposta de Sucesso (200 OK)

{
  "success": true,
  "message": "Agent action updated successfully",
  "data": {
    "id": "action-uuid-1",
    "name": "Schedule Meeting",
    "label": "Schedule Meeting",
    "description": "Schedule a meeting with the customer",
    "type": "webhook",
    "input_schema": [
      {
        "name": "date",
        "type": "string",
        "required": true,
        "description": "Meeting date"
      },
      {
        "name": "time",
        "type": "string",
        "required": true,
        "description": "Meeting time"
      }
    ],
    "config": null,
    "action_trigger": null,
    "url": "https://api.example.com/schedule",
    "authorization_url": "https://api.example.com/auth",
    "current_status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:30:00Z"
  }
}

Campos da Resposta

success

boolean

obrigatório

Indica se a operação foi bem-sucedida.

message

string

obrigatório

Mensagem de sucesso confirmando que a ação foi criada ou atualizada.

data

object

obrigatório

O objeto de ação criado ou atualizado.

Mostrar Objeto de Ação

string

obrigatório

Identificador único da ação.

name

string

obrigatório

O nome da ação.

label

string

obrigatório

Rótulo de exibição da ação.

description

string

obrigatório

Descrição detalhada do que a ação faz.

type

string

obrigatório

Tipo da ação. Opções: webhook, transfer, hold, etc.

input_schema

array

obrigatório

Array de parâmetros de entrada exigidos pela ação.

config

object

Objeto de configuração da ação (se aplicável).

action_trigger

object

Condições de gatilho para a ação (se aplicável).

url

string

URL do webhook para ações do tipo webhook.

authorization_url

string

URL de autorização para ações do tipo webhook.

current_status

string

obrigatório

Status atual da ação. Opções: active, inactive.

created_at

string

obrigatório

Timestamp ISO 8601 quando a ação foi criada.

updated_at

string

obrigatório

Timestamp ISO 8601 quando a ação foi atualizada pela última vez.

Respostas de Erro

Erro de Validação (422)

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ],
    "type": [
      "The selected type is invalid."
    ],
    "url": [
      "The url must be a valid URL."
    ],
    "authorization_url": [
      "The authorization url must be a valid URL."
    ]
  }
}

404 Não Encontrado

{
  "success": false,
  "message": "Agent not found"
}

401 Não Autorizado

{
  "success": false,
  "message": "Unauthenticated."
}

403 Proibido

{
  "success": false,
  "message": "You are not authorized to create actions for this agent."
}

500 Erro do Servidor

{
  "success": false,
  "message": "Internal server error."
}

Códigos de Erro

Código	Descrição	Status HTTP
`AGENT_NOT_FOUND`	O agente especificado não existe	404
`INVALID_TOKEN`	Token de autenticação inválido ou ausente	401
`UNAUTHORIZED`	O usuário não tem permissão para criar ações para este agente	403
`VALIDATION_ERROR`	A validação dos dados da requisição falhou	422
`SERVER_ERROR`	Erro interno do servidor ocorreu	500

Observações Importantes

O status do agente será definido como rascunho. Após criar ou atualizar ações, o agente será automaticamente definido como status “draft” e precisará ser publicado novamente para se tornar ativo.

Tipos de ação têm requisitos diferentes. Diferentes tipos de ação (webhook, transfer, hold) requerem parâmetros e configurações diferentes.

Validação de URL. Para ações de webhook, tanto url quanto authorization_url devem ser URLs válidas.

Melhores Práticas

Teste URLs de webhook - Sempre teste URLs de webhook antes de criar ações
Use nomes descritivos - Dê às ações nomes claros e descritivos
Valide entradas - Garanta que todos os parâmetros de entrada exigidos estejam adequadamente definidos
Trate erros graciosamente - Implemente tratamento adequado de erros para a execução das ações
Monitore o desempenho das ações - Acompanhe com que frequência as ações são acionadas e suas taxas de sucesso
Documente o comportamento das ações - Forneça descrições claras do que cada ação faz

Endpoints Relacionados

Listar Ações: GET /api/v1/agents/{agent_id}/actions
Excluir Ação: DELETE /api/v1/agents/{agent_id}/actions/{action_id}
Obter Agente: GET /api/v1/agents/{agent_id}
Publicar Agente: POST /api/v1/agents/{agent_id}/publish

Primeiros Passos

Conceitos

Referência da API

Guias

Criar/Atualizar Ação

Criar/Atualizar Ação

Endpoint

Parâmetros de Caminho

Cabeçalhos da Requisição

Corpo da Requisição

Exemplos de Requisição

Resposta

Resposta de Sucesso (200 OK)

Campos da Resposta

Respostas de Erro

Erro de Validação (422)

404 Não Encontrado

401 Não Autorizado

403 Proibido

500 Erro do Servidor

Códigos de Erro

Observações Importantes

Melhores Práticas

Endpoints Relacionados

Primeiros Passos

Conceitos

Referência da API

Guias

Documentation Index

​Criar/Atualizar Ação

​Endpoint

​Parâmetros de Caminho

​Cabeçalhos da Requisição

​Corpo da Requisição

​Exemplos de Requisição

​Resposta

​Resposta de Sucesso (200 OK)

​Campos da Resposta

​Respostas de Erro

​Erro de Validação (422)

​404 Não Encontrado

​401 Não Autorizado

​403 Proibido

​500 Erro do Servidor

​Códigos de Erro

​Observações Importantes

​Melhores Práticas

​Endpoints Relacionados

Criar/Atualizar Ação

Endpoint

Parâmetros de Caminho

Cabeçalhos da Requisição

Corpo da Requisição

Exemplos de Requisição

Resposta

Resposta de Sucesso (200 OK)

Campos da Resposta

Respostas de Erro

Erro de Validação (422)

404 Não Encontrado

401 Não Autorizado

403 Proibido

500 Erro do Servidor

Códigos de Erro

Observações Importantes

Melhores Práticas

Endpoints Relacionados