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

# Chamar o seu sistema

> Envia uma requisição fixa ao seu sistema e, se você quiser, deixa um funcionário AI continuar a conversa com a resposta

> [!NOTE]
>
> **Endpoint** · `POST /conversation/actions`

`send_json` **envia uma requisição ao seu sistema** —seu ERP, seu CRM, seu backend— com um
conteúdo que você escreve, sem que um modelo o redija. É a mesma ação «Chamar o seu
sistema» que a equipe do negócio configura em um action set pelo painel; aqui ela roda sozinha,
dentro de um grupo de ações.

Se você quiser, um funcionário AI **lê o que o seu sistema responder** e continua a conversa com o
cliente. Por exemplo: registrar o pedido e fazer o funcionário confirmar ao cliente o número que o
seu sistema devolveu.

Como ela se diferencia de um funcionário AI do tipo JSON:

* O funcionário JSON **redige** o corpo com um modelo a partir da conversa, e o marca com
  `is_test: true` quando roda no Tester.
* `send_json` envia **sempre o corpo que você escreveu**, byte a byte. O despacho não passa por um
  modelo nem consome tokens (a continuação, se você configurar uma, consome), e não leva nenhuma
  marca de teste.

**Campos**

* `url` — URL do seu sistema, `http://` ou `https://` (obrigatório, até 2000 caracteres). Sem
  usuário nem senha na URL: a autenticação vai em `headers`.
* `method` — `GET`, `POST`, `PUT` ou `PATCH`. Se omitido, `POST`.
* `headers` — cabeçalhos da requisição; por exemplo, a autenticação do seu sistema. O nome aceita
  letras, dígitos e hífens, e não são aceitos `Host`, `Content-Length`, `Transfer-Encoding`,
  `Connection`, `Keep-Alive`, `Upgrade` nem `Expect`; cada valor tem que ser Latin-1 (sem
  caracteres de controle ASCII exceto o tab): caso contrário a requisição é rejeitada com
  `400 INVALID_REQUEST`. Até 50 cabeçalhos, com o nome de até 256 caracteres e o valor de até 8192; juntos, nomes e
  valores somam até 16384.
* `query_params` — parâmetros adicionados à query string de `url`. Um com o mesmo nome de um parâmetro de `url` substitui a sua primeira ocorrência, no lugar, e as repetidas são descartadas; os demais pares são enviados como estão, sem ser codificados de novo (com `query_params`, os segmentos vazios, como `&&` ou um `&` final, são omitidos). Até 50 parâmetros, com os mesmos limites de nome e valor que `headers`, e a URL enviada —já codificada, com os parâmetros e com o path como a requisição o codifica— não pode passar de 8192 caracteres: um path com `ñ` ou acentos conta mais do que aparenta. Passado qualquer limite, a requisição é rejeitada com `400 INVALID_REQUEST`.
* `body` — o corpo, como **texto JSON** (até 10.000 caracteres). Não é aceito com `GET`.
* `wrap_key` — envolve o corpo sob essa chave (até 100 caracteres): com `"data"`, o seu sistema recebe
  `{"data":<body>}`. Exige `body`.
* `response_processor` — `{ ai_employee, instructions }`: o funcionário AI que lê a resposta e,
  opcionalmente, o que fazer com ela (até 500 caracteres).

```jsonc theme={null}
{
  "type": "send_json",
  "url": "https://erp.example.com/api/orders",
  "headers": { "Authorization": "Bearer <token do seu sistema>" },
  "body": "{\"sku\":\"A-100\",\"qty\":2,\"price\":150.50}",
  "response_processor": {
    "ai_employee": { "name": "Asistente de Ventas" },
    "instructions": "Confirme ao cliente o número do pedido que o sistema devolver."
  }
}
```

`send_json` não dispara o AI, mas **conta no limite de 3 ações que disparam o AI** por grupo, com
ou sem `response_processor`: a resposta dela pode continuar a conversa. Em uma lista, este objeto
vai no array `actions` de um `POST /conversation/actions` — veja [Montar uma lista de
ações](https://docs.1to1ai.com/pt/action-groups/overview.md#montar-uma-lista-de-ações).

## O corpo é texto, não um objeto

`body` é uma **string** com JSON dentro. É assim que ele sai **byte a byte**: o seu sistema recebe
exatamente esse texto, com as chaves na sua ordem e os números como você os escreveu —`150.50` não
vira `150.5`, e um inteiro de mais de 16 dígitos não perde precisão—. Com `wrap_key`, esse mesmo texto vai sem ser tocado dentro da envoltura: o seu sistema recebe `{"<wrap_key>":<body>}`. Se não for JSON válido, a
requisição é rejeitada com `400 INVALID_REQUEST` e nenhuma ação do grupo é executada.

É **fixo**: não leva variáveis nem dados da conversa, e a requisição também não leva cabeçalhos da
plataforma. Se o seu sistema precisa saber de qual conversa se trata, inclua isso você mesmo no
`body` ou em `query_params`.

Com corpo, a requisição leva `Content-Type: application/json`; para substituí-lo, passe-o em
`headers` com esse mesmo nome. Com `GET` não há corpo: os dados vão na URL ou em `query_params`.

## A resposta do seu sistema não faz a ação falhar

O seu sistema responder com erro, responder tarde ou não responder **não** é uma falha do
`send_json`: a ação conta como bem-sucedida, não dispara `stop_on_error` e não escala a conversa. A
ação só falha por algo do nosso lado, ou se `response_processor` não resolver (veja abaixo). No
Registro de atividade do painel ela aparece como bem-sucedida, com a nota de que o seu sistema
respondeu com erro ou não respondeu, ou de que não o chamamos porque a URL dele está bloqueada ou não
foi encontrada.

O que vale saber sobre a entrega:

* **O seu sistema tem 30 segundos para responder.** Se não responder a tempo, ou houver um erro de
  rede, a requisição **é repetida uma vez, idêntica**: se o seu sistema a processou mas demorou para
  responder, ele a recebe duas vezes. Se a requisição cria algo —um pedido, uma cobrança—, inclua o
  seu próprio identificador no `body` e deduplique por ele.
* **Reenviar o grupo a envia de novo.** `POST /conversation/actions` não deduplica: se você repetir
  um grupo com `send_json`, o seu sistema recebe a requisição de novo. Vale a mesma recomendação.
* **Uma resposta de erro não é repetida**, e um redirecionamento não é seguido.
* **A URL precisa resolver para um endereço público.** Um IP privado ou local é bloqueado e a
  requisição não sai.

> [!WARNING]
>
> **Os testes pelo Tester chegam ao seu sistema como reais.** `send_json` também despacha pelo Tester
> —o do painel, ou esta API sobre uma conversa de teste—, porque sem a resposta real do seu sistema
> não haveria nada para o funcionário AI ler.
>
> Diferente do funcionário AI do tipo JSON, **a requisição não leva nenhuma marca de teste**: sai
> idêntica a uma de produção. Se você não quer que um teste toque o seu sistema, aponte a ação para
> uma URL de testes enquanto testa.

## Continuar a conversa com a resposta

Com `response_processor`, o que o seu sistema responder pode ser lido por um funcionário AI para
continuar escrevendo ao cliente. Valem as mesmas regras da resposta do funcionário AI do tipo JSON,
descritas em [O que seu endpoint responde pode continuar a
conversa](https://docs.1to1ai.com/pt/webhooks.md#o-que-seu-endpoint-responde-pode-continuar-a-conversa):

* **O funcionário precisa ser operacional e estar ativo.** Se o nome não resolver para um, a ação
  falha com `AI_EMPLOYEE_NOT_FOUND` —ou `AMBIGUOUS_AI_EMPLOYEE`, se o nome coincidir com mais de
  um— e **a requisição não sai**. Não é validado no preflight: o grupo é aceito e a falha aparece ao
  executar.
* **Pode ser clássico ou v2 (novo motor).** Um v2 lê a resposta com seus poderes: se um deles
  volta a enviar dados ao seu sistema, essa resposta também conta no limite da cadeia abaixo. Se os
  funcionários v2 estiverem desligados na plataforma, a resposta não é processada e aparece um
  cartão de erro na conversa. Numa conversa de teste esse cartão não aparece.
* **Só é lida uma resposta `2xx` com corpo**, e o corpo é mostrado a um modelo: responda só com o
  que o cliente possa vir a saber.
* **A continuação roda depois**, em segundo plano e sem um prazo garantido.
* **Com outra ação de AI no grupo, o cliente pode receber duas respostas.** Se o mesmo grupo inclui
  `run_ai`, `ai_assistance` ou `assign_ai_employee` com `run: true`, essa ação responde ao cliente e
  a continuação volta a escrever com o que o seu sistema respondeu. As duas podem rodar **ao mesmo
  tempo**, não necessariamente uma depois da outra. Numa campanha, além disso, se a continuação
  assumir a conversa primeiro, a mensagem da ação de AI pode não sair. Se você quer uma resposta só,
  deixe que a continuação a dê.
* **A cadeia tem um teto.** Se a continuação despachar de novo para o seu sistema, essa resposta
  também pode continuar a conversa. Um `send_json` avulso em um grupo de ações começa a cadeia do
  início, então cabem **duas continuações**. Quantas cabem em cada caso está nessa mesma seção de
  webhooks.

> [!NOTE]
>
> **A própria ação também está sendo habilitada por etapas.** Enquanto não estiver habilitada na
> plataforma, um grupo que a inclui é rejeitado inteiro com `400 INVALID_REQUEST`, antes de executar
> qualquer coisa; se a plataforma não conseguiu confirmar se está habilitada, responde
> `500 FETCH_FAILED`, e você pode tentar de novo.

> [!NOTE]
>
> **Disponibilidade:** continuar a conversa com a resposta está sendo habilitado por etapas **no
> nível da plataforma**, não conta a conta. Enquanto não estiver habilitado, a resposta do seu
> sistema é registrada e não continua a conversa.

A equipe do negócio também pode usar `send_json` em uma campanha: ali sai **uma requisição por
destinatário** —veja [como elas chegam](https://docs.1to1ai.com/pt/webhooks.md#o-que-seu-endpoint-responde-pode-continuar-a-conversa)—.

## Exemplo executável

Um `send_json` sobre uma conversa identificada por telefone e canal: registra um pedido no seu
sistema e um funcionário AI confirma ao cliente o número que o seu sistema devolver.

### Request

```bash theme={null}
curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_json",
        "url": "https://erp.example.com/api/orders",
        "headers": { "Authorization": "Bearer <token do seu sistema>" },
        "body": "{\"sku\":\"A-100\",\"qty\":2,\"price\":150.50}",
        "response_processor": {
          "ai_employee": { "name": "Asistente de Ventas" },
          "instructions": "Confirme ao cliente o número do pedido que o sistema devolver."
        }
      }
    ]
  }'
```

### Resposta

`202 Accepted` — o grupo foi aceito e roda em **background**. O resultado real por ação não viaja
na resposta (consulte-o depois — veja [Como é
executado](https://docs.1to1ai.com/pt/action-groups/overview.md#como-é-executado)).

```json theme={null}
{
  "status": "processing",
  "actions_accepted": 1
}
```

**status** `string`

Sempre `processing`: confirma que o grupo foi aceito e está em execução.

**actions\_accepted** `integer`

Quantas ações do array foram **admitidas** para execução — não quantas tiveram sucesso.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.