> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar/Atualizar Ação

> Criar novas ações ou atualizar ações existentes para um agente de voz

# 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

<ParamField path="agent" type="string" required>
  O identificador único do agente de voz.
</ParamField>

## Cabeçalhos da requisição

<ParamField header="Authorization" type="string" required>
  Token Bearer para autenticação. Formato: `Bearer talq_your_environment_token_here`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Deve ser definido como `application/json`
</ParamField>

## Corpo da requisição

<ParamField body="node_id" type="string" required>
  ID do nó da ação para integração com o fluxo de trabalho
</ParamField>

<ParamField body="name" type="string" required>
  Nome da ação (máximo de 255 caracteres)
</ParamField>

<ParamField body="description" type="string" required>
  O que a ação faz
</ParamField>

<ParamField body="type" type="string" required>
  Tipo da ação. Opções: `webhook`, `transfer`, `hold`, etc.
</ParamField>

<ParamField body="inputs" type="array" required={false}>
  Array de parâmetros de entrada para a ação
</ParamField>

<ParamField body="integration" type="object" required={false}>
  Objeto de configuração da integração
</ParamField>

<ParamField body="url" type="string" required={false}>
  URL do webhook (deve ser uma URL válida — usada por ações `webhook`).
</ParamField>

<ParamField body="authorization_url" type="string" required={false}>
  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).
</ParamField>

<ParamField body="authorization_scheme" type="string" required={false}>
  Esquema de autorização usado ao chamar `url`. Opções: `none`, `bearer`, `basic`, `api_key`, `custom`. Padrão: `none`.
</ParamField>

<ParamField body="custom_headers" type="array" required={false}>
  Array de cabeçalhos HTTP customizados a enviar com a requisição do webhook. Cada item é `{ "key": "Header-Name", "value": "header-value" }`.
</ParamField>

<ParamField body="speak_on_send" type="string" required={false}>
  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.
</ParamField>

<ParamField body="speak_on_receive" type="string" required={false}>
  Frase que o agente dirá após o webhook responder com sucesso. A resposta do webhook pode ser referenciada via variáveis de template.
</ParamField>

<ParamField body="execution_mode" type="string" required={false}>
  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`)
</ParamField>

<ParamField body="hold_duration" type="integer" required={false}>
  Duração do hold em segundos (para ações `hold`).
</ParamField>

<ParamField body="transfer_to" type="string" required={false}>
  Número de telefone de destino da transferência no formato E.164 (para ações `transfer`).
</ParamField>

<ParamField body="current_status" type="string" required={false}>
  Status da ação. Opções: `active`, `inactive`. Padrão: `active`.
</ParamField>

## Exemplos de Requisição

<RequestExample>
  ```bash theme={null}
  # 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"
    }'
  ```

  ```javascript theme={null}
  // 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);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # 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"
    }'
  ```

  ```javascript theme={null}
  // 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);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # 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"
    }'
  ```

  ```javascript theme={null}
  // 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);
  ```
</RequestExample>

## Resposta

### Resposta de Sucesso (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### Campos da Resposta

<ResponseField name="success" type="boolean" required>
  Indica se a operação foi bem-sucedida.
</ResponseField>

<ResponseField name="message" type="string" required>
  Mensagem de sucesso confirmando que a ação foi criada ou atualizada.
</ResponseField>

<ResponseField name="data" type="object" required>
  O objeto de ação criado ou atualizado.

  <Expandable title="Objeto de Ação">
    <ResponseField name="id" type="string" required>
      Identificador único da ação.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      O nome da ação.
    </ResponseField>

    <ResponseField name="label" type="string" required>
      Rótulo de exibição da ação.
    </ResponseField>

    <ResponseField name="description" type="string" required>
      O que a ação faz.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Tipo da ação. Opções: `webhook`, `transfer`, `hold`, etc.
    </ResponseField>

    <ResponseField name="input_schema" type="array" required>
      Array de parâmetros de entrada exigidos pela ação.
    </ResponseField>

    <ResponseField name="config" type="object">
      Objeto de configuração da ação (se aplicável).
    </ResponseField>

    <ResponseField name="action_trigger" type="object">
      Condições de gatilho para a ação (se aplicável).
    </ResponseField>

    <ResponseField name="url" type="string">
      URL do webhook para ações do tipo webhook.
    </ResponseField>

    <ResponseField name="authorization_url" type="string">
      URL de autorização para ações do tipo webhook.
    </ResponseField>

    <ResponseField name="current_status" type="string" required>
      Status atual da ação. Opções: `active`, `inactive`.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      Timestamp ISO 8601 quando a ação foi criada.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      Timestamp ISO 8601 quando a ação foi atualizada pela última vez.
    </ResponseField>
  </Expandable>
</ResponseField>

## Respostas de erro

### Erro de Validação (422)

<ResponseExample>
  ```json theme={null}
  {
    "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."
      ]
    }
  }
  ```
</ResponseExample>

### 404 Não Encontrado

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Agent not found"
  }
  ```
</ResponseExample>

### 401 Não Autorizado

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthenticated."
  }
  ```
</ResponseExample>

### 403 Proibido

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "You are not authorized to create actions for this agent."
  }
  ```
</ResponseExample>

### 500 Erro do Servidor

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Internal server error."
  }
  ```
</ResponseExample>

## 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

<Info>
  **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.
</Info>

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

<Warning>
  **Validação de URL.** Para ações de webhook, tanto `url` quanto `authorization_url` devem ser URLs válidas.
</Warning>

## 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`