Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

📥Broadcasts

Os Broadcasts representam o envio de SMS em massa. Através destes endpoints você pode disparar mensagens, listar e consultar seus envios, acompanhar o status individual de cada mensagem e cancelar um envio em andamento.

A URL de base de todos os endpoints é: https://web.smsfunnel.com.br/api/parceiros/v1

Os endpoints de listagem utilizam paginação simples. A resposta traz current_page, data, per_page, next_page_url e prev_page_url — não há campos total ou last_page. Para navegar, utilize o parâmetro de query page.

Status possíveis

Status do broadcast: pending, scheduled, sending, sent, sent_with_errors, cancelled, sanitizing, importing.

Status da mensagem: queued (aceita, aguardando disparo), sent (enviada), delivered (entrega confirmada), failed (falha) e undelivered (não entregue).

Endpoints

POST /sms/messages

Função: Enfileira o disparo de uma ou mais mensagens SMS. Cada chamada gera um ou mais broadcasts (um por grupo de agendamento) que agrupam as mensagens enviadas.

Corpo de envio:

{
    // Campos globais (opcionais) - aplicados a todas as mensagens, salvo quando sobrescritos por mensagem.
    "from": "SMSFunnel", // Remetente personalizado (até 20 caracteres)
    "flashSms": false, // Envio como flash SMS
    "concat": true, // Concatenação de mensagens longas
    "schedule": "2026-07-01T10:00:00Z", // Agendamento global
    "url": "https://example.com/promo", // "Meu Link". Obrigatório quando alguma mensagem contém {meu_link}.
    "messages": [ // Obrigatório. De 1 a 5000 mensagens.
        {
            "to": "+5511999999999", // Obrigatório. 10 a 15 dígitos, com DDI/DDD (aceita "+").
            "message": "Oferta: {meu_link}", // Obrigatório. 1 a 1530 caracteres.
            "reference": "order-123" // Opcional. Seu identificador (até 100 caracteres). Se omitido, geramos um.
        },
        {
            "to": "5511888888888",
            "message": "Ola!",
            "schedule": "2026-07-01T11:00:00", // Sobrescreve o agendamento global desta mensagem
            "from": "LOJA" // Sobrescreve o remetente global desta mensagem
        }
    ]
}

Agendamento (schedule): aceita os formatos 2026-07-01T10:00:00Z (ISO 8601 com offset), 2026-07-01T10:00:00 (ISO 8601 sem offset) ou 2026-07-01 10:00:00. A data deve ser futura. Os campos por mensagem têm prioridade sobre os globais.

Quando alguma mensagem contém a variável {meu_link}, o campo url é obrigatório (e vice-versa). Nós encurtamos o link automaticamente e substituímos {meu_link} pelo link curto em cada mensagem.

Idempotência (opcional): envie o header Idempotency-Key (máx. 80 caracteres) para evitar envios duplicados. Se recebermos a mesma chave em até 24 horas, retornamos a resposta original sem reprocessar, incluindo o header Idempotency-Replayed: true.

Corpo de resposta — 202 Accepted:

GET /sms/broadcasts

Função: Lista seus broadcasts, do mais recente para o mais antigo.

Parâmetros de query (opcionais):

Corpo de resposta — 200 OK:

GET /sms/broadcasts/{id}

Função: Obtém os detalhes de um broadcast específico, incluindo suas métricas.

Corpo de resposta — 200 OK:

GET /sms/broadcasts/{id}/contacts

Função: Lista os contatos (mensagens individuais) de um broadcast.

Parâmetros de query (opcionais):

Corpo de resposta — 200 OK:

GET /sms/messages/{external_message_id}

Função: Consulta o status de uma mensagem específica, pelo id retornado no envio.

Corpo de resposta — 200 OK:

PUT /sms/broadcasts/{id}/cancel

Função: Cancela um broadcast. Apenas broadcasts nos status pending, scheduled ou sending podem ser cancelados.

Corpo de resposta:

  • 200 OK — broadcast pending ou scheduled: cancelamento completo (cancellation: "complete").

  • 202 Accepted — broadcast sending: cancelamento parcial; mensagens já enfileiradas ainda podem ser disparadas (cancellation: "partial").

Broadcasts já finalizados (sent, sent_with_errors) ou já cancelados (cancelled) retornam 409 INVALID_STATUS_TRANSITION, com o status atual em details.current_status.

Código de Erros Comuns

  • 401 Unauthorized (UNAUTHORIZED): Não foi possível identificar o parceiro a partir da Chave de API.

  • 402 Payment Required (INSUFFICIENT_CREDITS): Créditos de SMS insuficientes para o envio.

  • 404 Not Found (NOT_FOUND): O broadcast ou a mensagem não foi encontrada ou não pertence à sua conta.

  • 409 Conflict (INVALID_STATUS_TRANSITION): O broadcast não pode ser cancelado no status atual.

  • 422 Unprocessable Entity (VALIDATION_ERROR): Algum campo do corpo da requisição é inválido (inclui {meu_link} sem url e Idempotency-Key acima de 80 caracteres).

  • 429 Too Many Requests (RATE_LIMIT_EXCEEDED): Limite de 60 requisições por minuto excedido. Consulte o header Retry-After.

  • 502 Bad Gateway (SHORTENER_UNAVAILABLE): Falha temporária ao encurtar o link de "Meu Link". Tente novamente.

Corpo de resposta de erro:

Dúvidas?

Em caso de dúvidas, entre em contato com nosso suporte.

PreviousSequênciasNextReferência

Last updated