Pular para o conteúdo principal
POST
/
api
/
v1
/
agents
/
{agent_id}
/
actions
# 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"
  }'

{
  "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"
  }
}

​
Criar/Atualizar Ação

Criar novas ações ou atualizar ações existentes para um agente de voz. Configura 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.

​
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
O 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": "+5511987654321"
      }
    ],
    "transfer_to": "+5511987654321",
    "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.

​
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ódigoDescriçãoStatus HTTP
AGENT_NOT_FOUNDO agente especificado não existe404
INVALID_TOKENToken de autenticação inválido ou ausente401
UNAUTHORIZEDO usuário não tem permissão para criar ações para este agente403
VALIDATION_ERRORA validação dos dados da requisição falhou422
SERVER_ERRORErro interno do servidor ocorreu500

​
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

  1. Teste URLs de webhook - Sempre teste URLs de webhook antes de criar ações
  2. Use nomes descritivos - Dê às ações nomes claros e descritivos
  3. Valide entradas - Garanta que todos os parâmetros de entrada exigidos estejam adequadamente definidos
  4. Trate erros graciosamente - Implemente tratamento adequado de erros para a execução das ações
  5. Monitore o desempenho das ações - Acompanhe com que frequência as ações são acionadas e suas taxas de sucesso
  6. 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