Chamar o seu sistema

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

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

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

O corpo é texto, não um objeto

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

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

Continuar a conversa com a resposta

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

Exemplo executável

Request

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

{
  "status": "processing",
  "actions_accepted": 1
}