Primeiros passos

Este guia te leva do zero à sua primeira mensagem de WhatsApp enviada pela API.

Obtenha sua API key

A API key é emitida pelo dashboard, em Configurações → API. Ela tem o prefixo sk_1to1_.

A API key dá acesso completo às conversas do seu negócio. Trate-a como um segredo — nunca a coloque em código cliente nem a suba a um repositório.

Identifique seu negócio

Todos os endpoints partem de uma base URL que inclui o {slug} do seu negócio:

https://app.1to1.ai/api/v1/public/{slug}

O {slug} também está nas configurações da API. A key e o slug devem corresponder ao mesmo negócio.

Obtenha a chave do seu canal

Toda requisição leva a chave do canal (channel), obrigatória em cada envio. Você a copia do dashboard em Configurações → Canais: abra seu canal de WhatsApp e copie o campo Chave do canal (tem o prefixo ch_). Você também pode listá-las com GET /channels, que retorna cada canal com sua key.

A chave aparece ao editar um canal já conectado. Se você acabou de criar um, salve-o e reabra para vê-la.

Envie sua primeira mensagem

Um POST a /conversation/actions com uma ação send_message, e a conversa identificada por telefone e canal:

curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+5215512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "body": "Olá 👋, como posso ajudar?"
      }
    ]
  }'

const res = await fetch(
  "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_1to1_sua_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      conversation: { phone: "+5215512345678", channel: "ch_7A9K2M4Q" },
      actions: [
        { type: "send_message", body: "Olá 👋, como posso ajudar?" },
      ],
    }),
  },
);

import requests

requests.post(
    "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions",
    headers={"Authorization": "Bearer sk_1to1_sua_api_key"},
    json={
        "conversation": {"phone": "+5215512345678", "channel": "ch_7A9K2M4Q"},
        "actions": [
            {"type": "send_message", "body": "Olá 👋, como posso ajudar?"}
        ],
    },
)

Trate a resposta

Uma resposta 202 confirma que o grupo foi aceito; as ações rodam em background:

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

O 202 não garante que cada ação teve sucesso — o resultado por ação não viaja na resposta. Consulte-o no estado da conversa ou no activity log do negócio.Se a validação falhar, a API responde um 4xx síncrono e nenhuma ação é executada. Os erros retornam { code, message }; ambos os campos são garantidos. Faça switch sobre code (estável), nunca sobre message (texto humano, pode ser refinado entre versões):

{ "code": "CONVERSATION_NOT_FOUND", "message": "..." }

Rate limit: 60 requisições/min por API key. Ao exceder você recebe um 429 com o header Retry-After. Ver Rate limits.

Introdução

Conceitos

Guias

Ações

Próximos passos

Conversas

Mensagens

​Próximos passos

Conversas

Mensagens

Próximos passos