Quickstart

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):

https://api.octasend.com.br/functions/v1

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.

No menu lateral, acesse Configurações → Canais. Cada canal liberado aparece como Configurado ou Não configurado.
Clique em Configurar no canal Email (ou em Editar, se ele já estiver configurado).
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.
Preencha as credenciais do provedor. Se quiser, clique em Testar Conexão para validar antes de gravar.
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.

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
SMS	Escolha o provedor (SendPulse ou Twilio), clique em Configurar, preencha as credenciais e clique em Salvar Configuração	SMS
Slack, Telegram, Web Push	Preencha as credenciais e clique em Salvar Configuração	Slack, Telegram, Web Push
Push Notification (Mobile)	Preencha as credenciais da sua conta AWS e clique em Salvar Configuração	Push mobile
In-app	Não tem credenciais. Basta instalar o widget ou a OctaTag no seu produto	Widget In-App

2. Crie uma comunicação

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

Acesse Comunicações → Templates e clique em Nova Comunicação.
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.
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

Na seção Canais, clique no cartão Email (+ Adicionar canal) para incluir o canal na comunicação.
Clique de novo no cartão, que agora mostra Clique para editar.
Em Adicionar idioma, escolha o idioma, por exemplo Português (Brasil).
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.
Clique em Salvar Configuração. A versão salva fica Ativa e já pode ser enviada.

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.

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

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

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.

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:

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

6. Envie a mensagem

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:

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

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 e a mensagem foi adiada	Nada: ela sai quando o limite liberar. Para volumes grandes, veja o envio em lote em Enviar mensagens

Próximos passos

Autenticação

Detalhes do fluxo OAuth 2.0 Client Credentials

Enviar mensagens

Todos os parâmetros do endpoint send-message e envio em lote

Comunicações

Canais, idiomas, versões e envio de teste

Guias de canais

Configure WhatsApp, SMS, Slack, Web Push e mais

Consultar logs

Histórico de envios com filtros

Automações

Mensagens que disparam sozinhas, sem chamar a API a cada envio

Primeiros Passos

Mensageria

Guias de Canais

Atendimento e IA

Site e engajamento

E-commerce

Integrações

Conta e ferramentas

API Reference

Antes de começar

1. Configure e ative o canal

2. Crie uma comunicação

3. Escreva o template do canal

4. Crie suas credenciais

5. Obtenha um access token

6. Envie a mensagem

Se a mensagem não saiu

Próximos passos

Autenticação

Enviar mensagens

Comunicações

Guias de canais

Consultar logs

Automações

​Antes de começar

​1. Configure e ative o canal

​2. Crie uma comunicação

​3. Escreva o template do canal

​4. Crie suas credenciais

​5. Obtenha um access token

​6. Envie a mensagem

​Se a mensagem não saiu

​Próximos passos

Autenticação

Enviar mensagens

Comunicações

Guias de canais

Consultar logs

Automações

Antes de começar

1. Configure e ative o canal

2. Crie uma comunicação

3. Escreva o template do canal

4. Crie suas credenciais

5. Obtenha um access token

6. Envie a mensagem

Se a mensagem não saiu

Próximos passos