# 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 1: Create webhook action
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
  })
});

const result = await response.json();
console.log(result);

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

POST

api

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

// Request 1: Create webhook action
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
  })
});

const result = await response.json();
console.log(result);

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

string

obrigatório

O identificador único do agente de voz.

Cabeçalhos da requisição

string

obrigatório

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

string

obrigatório

Deve ser definido como application/json

Corpo da requisição

string

obrigatório

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

string

obrigatório

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

string

obrigatório

O que a ação faz

string

obrigatório

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

array

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

object

Objeto de configuração da integração

string

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

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).

string

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

array

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

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.

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.

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)

integer

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

string

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

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 1: Create webhook action
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
  })
});

const result = await response.json();
console.log(result);

# 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 2: Create transfer action
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
  })
});

const result = await response.json();
console.log(result);

# 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"
  }'

// Request 3: Create hold action
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
  })
});

const result = await response.json();
console.log(result);

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

boolean

obrigatório

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

string

obrigatório

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

object

obrigatório

O objeto de ação criado ou atualizado.

Mostrar Objeto de Ação

string

obrigatório

Identificador único da ação.

string

obrigatório

O nome da ação.

string

obrigatório

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

string

obrigatório

O que a ação faz.

string

obrigatório

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

array

obrigatório

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

object

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

object

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

string

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

string

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

string

obrigatório

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

string

obrigatório

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

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

​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