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

# Quickstart

> Envie sua primeira mensagem com o OctaSend em poucos minutos

Neste guia você configura um canal, cria uma comunicação com um template, gera suas credenciais e envia a primeira mensagem pela API. O exemplo usa o canal de e-mail. Os outros canais seguem o mesmo caminho.

## Antes de começar

* Você precisa de acesso ao painel da sua conta.
* Os canais que aparecem no painel são os liberados para a sua conta. Se o canal que você quer usar não aparece, fale com a OctaSend.
* Todas as chamadas da API usam esta base (só HTTPS):

```text theme={null}
https://api.octasend.com.br/functions/v1
```

> [!TIP]
>
> Em **Configurações → OAuth Clients**, o painel mostra as URLs completas dos endpoints, prontas para copiar, e exemplos de código em cURL, JavaScript, PHP e Python.

## 1. Configure e ative o canal

Antes de enviar, o canal precisa estar configurado na sua conta. Sem isso, o envio por ele falha.

1. No menu lateral, acesse **Configurações → Canais**. Cada canal liberado aparece como **Configurado** ou **Não configurado**.
2. Clique em **Configurar** no canal **Email** (ou em **Editar**, se ele já estiver configurado).
3. Escolha o provedor que vai enviar os seus e-mails (Amazon SES, SMTP, SendGrid (Twilio) ou SendPulse, conforme os liberados para a sua conta) e clique em **Configurar**.
4. Preencha as credenciais do provedor. Se quiser, clique em **Testar Conexão** para validar antes de gravar.
5. Clique em **Salvar**.

Ao salvar, o canal fica ativo e passa a aparecer como **Configurado** na lista. No e-mail, só um provedor fica ativo por vez, marcado como **Ativo**.

> [!WARNING]
>
> Todo canal, menos o In-app, precisa de configuração ativa em **Configurações → Canais**. Se você enviar por um canal que não foi configurado, a API responde com `"status": "failed"` e `"error": "Channel not configured"` para aquele canal, e nada é entregue.

Nos outros canais o caminho é o mesmo, com os campos de cada um:

| Canal | O que fazer em Configurações → Canais | Guia |
| - | - | - |
| WhatsApp | Na aba **Conexões**, clique em **Adicionar conexão** (Meta Cloud API ou Evolution API) | [WhatsApp](https://docs.octasend.com.br/guias/whatsapp.md) |
| SMS | Escolha o provedor (SendPulse ou Twilio), clique em **Configurar**, preencha as credenciais e clique em **Salvar Configuração** | [SMS](https://docs.octasend.com.br/guias/sms.md) |
| Slack, Telegram, Web Push | Preencha as credenciais e clique em **Salvar Configuração** | [Slack](https://docs.octasend.com.br/guias/slack.md), [Telegram](https://docs.octasend.com.br/guias/telegram.md), [Web Push](https://docs.octasend.com.br/guias/web-push.md) |
| Push Notification (Mobile) | Preencha as credenciais da sua conta AWS e clique em **Salvar Configuração** | [Push mobile](https://docs.octasend.com.br/guias/push-mobile.md) |
| In-app | Não tem credenciais. Basta instalar o widget ou a OctaTag no seu produto | [Widget In-App](https://docs.octasend.com.br/api-reference/widget-in-app.md) |

## 2. Crie uma comunicação

A comunicação é o que a API dispara, identificada pelo **slug**.

1. Acesse **Comunicações → Templates** e clique em **Nova Comunicação**.
2. Preencha o **Nome** (ex.: `Boas Vindas`). Ao sair do campo, o **Slug** é gerado a partir do nome (`boas-vindas`). O slug aceita só letras minúsculas, números, hífen e sublinhado, e não pode se repetir na sua conta.
3. Clique em **Criar Comunicação**.

Toda comunicação nasce ativa. O painel abre a tela dela, com a seção **Canais**.

## 3. Escreva o template do canal

1. Na seção **Canais**, clique no cartão **Email** (**+ Adicionar canal**) para incluir o canal na comunicação.
2. Clique de novo no cartão, que agora mostra **Clique para editar**.
3. Em **Adicionar idioma**, escolha o idioma, por exemplo **Português (Brasil)**.
4. Preencha o **Título da versão** (nome interno, ex.: `Versão 1`), o **Assunto** e o corpo do e-mail. Use `{{nome}}` onde quiser inserir o valor da variável `nome` enviada pela API.
5. Clique em **Salvar Configuração**. A versão salva fica **Ativa** e já pode ser enviada.

> [!TIP]
>
> Para testar sem código, preencha o **Destinatário de Teste** em **Configurações → Geral** e clique em **Enviar teste** no editor do template. O template precisa estar salvo antes do teste.

> [!NOTE]
>
> Quando a chamada não informa `language`, a OctaSend usa o **Idioma padrão** da sua conta (em **Configurações → Geral**) e depois o **Idioma de fallback**. Se o canal tiver um único template ativo, ele é usado qualquer que seja o idioma.

## 4. Crie suas credenciais

1. Acesse **Configurações → OAuth Clients**.
2. Digite um nome para a integração (ex.: `Loja Virtual – Produção`) e clique em **Criar**.
3. Copie o `client_id` e o `client_secret` e guarde-os em variáveis de ambiente do seu servidor.

> [!WARNING]
>
> O `client_secret` só é exibido uma vez, logo após a criação. Se perder, clique em **Revogar** no client e crie outro. A revogação invalida na hora todos os access tokens daquele client.

Nunca coloque o `client_secret` no frontend (JavaScript do navegador). As chamadas abaixo são feitas pelo seu servidor.

## 5. Obtenha um access token

Troque as credenciais por um access token. O endpoint aceita JSON ou `application/x-www-form-urlencoded`.

```bash theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/oauth-token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "SEU_CLIENT_ID",
    "client_secret": "SEU_CLIENT_SECRET"
  }'
```

Resposta:

```json theme={null}
{
  "access_token": "at_f4a92b...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "send"
}
```

O token vale por 1 hora (`expires_in` em segundos). Guarde-o em cache e peça um novo perto de expirar. Veja os detalhes em [Autenticação](https://docs.octasend.com.br/api-reference/autenticacao.md).

## 6. Envie a mensagem

```bash theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/send-message \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "communication_slug": "boas-vindas",
    "recipient": { "email": "usuario@exemplo.com" },
    "variables": { "nome": "Ricardo" }
  }'
```

A resposta traz um resultado por canal da comunicação:

```json theme={null}
{
  "success": true,
  "results": [
    {
      "channel": "email",
      "status": "sent",
      "provider_message_id": "010f018e...",
      "log_id": "..."
    }
  ]
}
```

Cada envio fica registrado em **Comunicações → Logs**, com o status e o erro, se houver. Veja [Logs de mensagens](https://docs.octasend.com.br/plataforma/logs-de-mensagens.md).

## Se a mensagem não saiu

| O que a API devolveu | Por quê | O que fazer |
| - | - | - |
| HTTP 401, `Invalid, expired or revoked token` | O access token venceu (1 hora) ou o client foi revogado | Peça um novo token no passo 5 |
| HTTP 400, `communication_slug is required` | O campo `communication_slug` não foi enviado | Inclua o slug no corpo |
| HTTP 404, `Communication not found` | O slug não existe na sua conta ou a comunicação está inativa | Confira o slug em **Comunicações → Templates** |
| `"status": "failed"` com `"error": "Channel not configured"` | O canal não tem configuração ativa | Faça o passo 1 para esse canal |
| `"status": "skipped"` com `"error": "No template found for any language"` | O canal não tem template ativo que sirva ao idioma do envio | Crie ou ative uma versão do template, ou informe `language` na chamada |
| `"results": []` | O destinatário não tem o dado que o canal exige (ex.: sem `recipient.email` no e-mail), então o canal foi pulado, ou a comunicação não tem canais | Inclua o dado do destinatário. Se você informar `channels` na chamada, a resposta diz qual campo falta |
| `"deferred": true` com `"status": "queued"`, sem `results` | A conta passou do [limite de mensagens por minuto](https://docs.octasend.com.br/api-reference/enviar-mensagens.md#limite-de-envio-por-minuto) e a mensagem foi adiada | Nada: ela sai quando o limite liberar. Para volumes grandes, veja o envio em lote em [Enviar mensagens](https://docs.octasend.com.br/api-reference/enviar-mensagens.md) |

## Próximos passos

> [card] [Autenticação](https://docs.octasend.com.br/api-reference/autenticacao.md)
>
> Detalhes do fluxo OAuth 2.0 Client Credentials

> [card] [Enviar mensagens](https://docs.octasend.com.br/api-reference/enviar-mensagens.md)
>
> Todos os parâmetros do endpoint send-message e envio em lote

> [card] [Comunicações](https://docs.octasend.com.br/plataforma/comunicacoes.md)
>
> Canais, idiomas, versões e envio de teste

> [card] [Guias de canais](https://docs.octasend.com.br/guias/whatsapp.md)
>
> Configure WhatsApp, SMS, Slack, Web Push e mais

> [card] [Consultar logs](https://docs.octasend.com.br/api-reference/consultar-logs.md)
>
> Histórico de envios com filtros

> [card] [Automações](https://docs.octasend.com.br/plataforma/automacoes.md)
>
> Mensagens que disparam sozinhas, sem chamar a API a cada envio


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