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

# Primeiros passos

> Autentique sua primeira requisição e envie uma mensagem de WhatsApp em minutos.

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

<Steps>
  <Step title="Obtenha sua API key">
    A API key é emitida pelo dashboard, em **Configurações → API**. Ela tem o
    prefixo `sk_1to1_`.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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`.

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

  <Step title="Envie sua primeira mensagem">
    Um `POST` a `/conversation/actions` com uma ação `send_message`, e a conversa
    identificada por telefone e canal:

    <CodeGroup>
      ```bash cURL theme={null}
      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?"
            }
          ]
        }'
      ```

      ```js JavaScript theme={null}
      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?" },
            ],
          }),
        },
      );
      ```

      ```python Python theme={null}
      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?"}
              ],
          },
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Trate a resposta">
    Uma resposta `202` confirma que o grupo foi **aceito**; as ações rodam em
    background:

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

    ```json theme={null}
    { "code": "CONVERSATION_NOT_FOUND", "message": "..." }
    ```
  </Step>
</Steps>

<Note>
  **Rate limit:** 60 requisições/min por API key. Ao exceder você recebe um `429`
  com o header `Retry-After`. Ver [Rate limits](/pt/rate-limits).
</Note>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Conversas" icon="comments" href="/pt/conversations">
    Como identificar uma conversa e a janela de 24h.
  </Card>

  <Card title="Mensagens" icon="paper-plane" href="/pt/messages">
    As quatro formas de enviar uma mensagem.
  </Card>
</CardGroup>