API Sendblue

Visão Geral

Sendblue é uma API REST que envia iMessage (bolhas azuis), SMS e RCS de um número de telefone provisionado. Tudo é JSON puro sobre HTTPS — nenhum SDK é necessário. A API cobre envios 1:1 e em grupo de saída, efeitos de iMessage, reações, indicadores de digitação, callbacks de status e webhooks de entrada.

Quando Usar Esta Habilidade

• Use ao escrever código de aplicação (servidor, worker, função) que envia mensagens Sendblue como parte de um serviço de longa duração.
• Use ao receber mensagens de entrada via webhooks.
• Use quando precisar de recursos que o CLI não expõe: estilos de envio, reações, mensagens em grupo, indicadores de digitação, callbacks de status, uploads de mídia ou a API de contatos além do CRUD básico.
• Opte pelo [[sendblue-cli]] em vez disso para envios no contexto do shell: scripts pontuais, cron jobs, ganchos de agente, fluxos de trabalho "me avise quando X".

Como Funciona

Passo 1: Autenticar

https://api.sendblue.com

Cada requisição precisa de dois cabeçalhos:

sb-api-key-id: <YOUR_API_KEY_ID>
sb-api-secret-key: <YOUR_API_SECRET>
Content-Type: application/json

Mantenha ambos os valores no lado do servidor — nunca os envie para um navegador ou cliente móvel.

Passo 2: Enviar uma mensagem

curl -X POST https://api.sendblue.com/api/send-message \
  -H "sb-api-key-id: $KEY_ID" \
  -H "sb-api-secret-key: $SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "+15551234567",
    "from_number": "+1YOUR_SENDBLUE_NUMBER",
    "content": "Hello from the API!"
  }'

Números de telefone devem estar em E.164. from_number deve ser uma linha que você possui — liste as suas com GET /api/lines.

Passo 3: Rastrear entrega

A resposta síncrona inclui um message_handle (GUID da Apple — persista isso; você precisará dele para reações e respostas) e um status de REGISTERED, PENDING, QUEUED, ACCEPTED, SENT, DELIVERED, DECLINED, ERROR. Apenas DELIVERED significa que chegou. Use status_callback em vez de fazer polling em /api/status.

Passo 4: Receber entrada

Configure URLs de webhook no painel ou via POST /api/account/webhooks. Sendblue envia POSTs de JSON para o seu endpoint. Responda com 2xx prontamente — não-2xx aciona novas tentativas e entregas duplicadas. Tipos de evento: receive, outbound, typing_indicator, call_log, line_blocked, line_assigned, contact_created.

Endpoints Principais

Exemplos

Exemplo 1: Enviar com mídia, efeitos e um callback de status

POST /api/send-message
{
  "number": "+15551234567",
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "content": "Optional text",
  "media_url": "https://example.com/img.jpg",
  "send_style": "celebration",
  "status_callback": "https://yourapp.com/sendblue/status"
}

content e/ou media_url é obrigatório. send_style é apenas para iMessage — valores válidos: celebration, shooting_star, fireworks, lasers, love, confetti, balloons, spotlight, echo, invisible, gentle, loud, slam. Ignorado em SMS. Texto de até 18.996 caracteres; mídia de até 100 MB no iMessage, 5 MB no SMS.

Exemplo 2: Mensagem em grupo

POST /api/send-group-message
{
  "numbers": ["+15551234567", "+15557654321"],
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "content": "Hey team"
}

A resposta retorna um group_id — persista-o para enviar acompanhamentos na mesma thread em vez de criar uma nova a cada vez.

Exemplo 3: Reagir a uma mensagem

POST /api/send-reaction
{
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "message_handle": "<message_handle from prior send>",
  "reaction": "love"
}

…