> For the complete documentation index, see [llms.txt](https://docs.smsfunnel.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smsfunnel.com.br/api/parceiros/broadcasts.md).

# 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.

{% hint style="success" %}
**A URL de base de todos os endpoints é**: <https://web.smsfunnel.com.br/api/parceiros/v1>
{% endhint %}

{% hint style="info" %}
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`.
{% endhint %}

**Status possíveis**

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

**Status da mensagem:** `queued` (aceita, aguardando disparo), `sent_to_carrier` (despachada para envio — estado final da maioria dos envios), `delivered` (entrega confirmada no aparelho), `cancelled` (não saiu: cancelada por você, telefone inválido ou saldo insuficiente — nada é cobrado), `blocked_blacklist` (não saiu: telefone na sua blacklist — nada é cobrado) e `blocked_content` (não saiu: barrada por política de conteúdo).

***

#### Endpoints

<mark style="color:green;">**POST**</mark>**&#x20;/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:**

```json5
{
    // Campos globais (opcionais) - aplicados a todas as mensagens, salvo quando sobrescritos por mensagem.
    "from": "SMSFunnel", // Não suportado no momento — devolvido em unsupported_features
    "flashSms": false, // Não suportado no momento — devolvido em unsupported_features
    "concat": true, // Não suportado no momento — devolvido em unsupported_features
    "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
        }
    ]
}
```

{% hint style="info" %}
**Agendamento (`schedule`):** aceita os formatos `2026-07-01T10:00:00Z` (ISO 8601 com offset), `2026-07-01T10:00:00` (ISO 8601 sem offset, interpretado no horário de Brasília) ou `2026-07-01 10:00:00`. A data deve ser futura. Os campos por mensagem têm prioridade sobre os globais.

Mensagens com agendamentos diferentes geram **um broadcast por agendamento**. A resposta traz em `broadcast_id` apenas o primeiro; use o `id` de cada mensagem (`GET /sms/messages/{id}`) ou a listagem `GET /sms/broadcasts` para acompanhar os demais.
{% endhint %}

{% hint style="warning" %}
**Janela de envio:** disparos e agendamentos só são aceitos entre **07:00 e 22:00** (horário de Brasília). Vale tanto para o horário da requisição quanto para cada `schedule` do lote. Fora dela, a resposta é `403 OUTSIDE_SEND_WINDOW`, com a janela em `details.window`.
{% endhint %}

{% hint style="info" %}
**Intervalo mínimo entre disparos:** se a sua conta tem a opção "Forçar intervalo para broadcast" ativa, cada disparo precisa respeitar o intervalo configurado (padrão de 30 minutos) em relação aos disparos já agendados e aos demais agendamentos do mesmo lote. Caso contrário, a resposta é `409 BROADCAST_INTERVAL_NOT_RESPECTED`.
{% endhint %}

{% hint style="warning" %}
**Saldo:** contas no pacote de créditos recebem `402 INSUFFICIENT_CREDITS` quando os créditos não cobrem o lote, e nada é criado. Contas cobradas pela **Carteira** sempre recebem `202`: o saldo é conferido no processamento, e o que ele não cobrir fica com status `cancelled` (envio parcial). Veja Saldo e Carteira.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
**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`.
{% endhint %}

**Corpo de resposta — `202 Accepted`:**

```json5
{
    "broadcast_id": "9b1f8e2a-7b31-7c4e-9a1d-2f3b4c5d6e7f", // ID do broadcast gerado
    "messages": [
        {
            "id": "0190c8e2-abab-7da9-9a46-4da50bd49147", // ID da mensagem (external_message_id)
            "reference": "order-123", // Sua referência (ou a gerada por nós)
            "phone": "5511999999999", // Telefone normalizado
            "status": "queued", // Status inicial
            "bill_factor": 1 // Unidades cobradas por esta mensagem (sempre 1)
        }
    ],
    "unsupported_features": ["flashSms", "concat", "from"] // Recursos solicitados que não foram aplicados, se houver
}
```

{% hint style="info" %}
`from`, `flashSms` e `concat` são aceitos no corpo por compatibilidade, mas **ainda não são suportados**: quando enviados, voltam em `unsupported_features` e a mensagem é enviada normalmente, sem eles.
{% endhint %}

***

<mark style="color:green;">**GET**</mark>**&#x20;/sms/broadcasts**

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

**Parâmetros de query (opcionais):**

```json5
{
    "status": "sending", // Filtra por status (ver lista de status do broadcast)
    "start_date": "2026-06-01", // Filtra por created_at >= data (YYYY-MM-DD)
    "end_date": "2026-06-30", // Filtra por created_at <= data (YYYY-MM-DD)
    "text": "Carnaval", // Busca pelo nome do broadcast
    "per_page": 50, // Itens por página. Padrão: 50. Mínimo: 1, Máximo: 200 (valores fora da faixa são ajustados).
    "page": 1 // Página desejada
}
```

**Corpo de resposta — `200 OK`:**

```json5
{
    "current_page": 1,
    "data": [
        {
            "id": "9b1f8e2a-7b31-7c4e-9a1d-2f3b4c5d6e7f", // ID do broadcast
            "name": "Campanha X", // Nome do broadcast
            "message": "Oferta: {meu_link}", // Mensagem enviada
            "status": "sending", // Status atual
            "scheduled_date": "2026-07-01T10:00:00-03:00", // Data de agendamento (ou nulo)
            "leads_count": 1500, // Quantidade de destinatários
            "partner_reference": "ref-abc", // Sua referência
            "flash_sms": false, // Sempre false (recurso não suportado)
            "concat": false, // Sempre false (recurso não suportado)
            "from": null, // Sempre null (recurso não suportado)
            "idempotency_key": "key-123", // Chave de idempotência
            "created_at": "2026-06-30T14:00:00-03:00" // Data de criação
        }
    ],
    "first_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/broadcasts?page=1",
    "from": 1,
    "next_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/broadcasts?page=2",
    "path": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/broadcasts",
    "per_page": 50,
    "prev_page_url": null,
    "to": 50
}
```

***

<mark style="color:green;">**GET**</mark>**&#x20;/sms/broadcasts/{id}**

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

**Corpo de resposta — `200 OK`:**

```json5
{
    "id": "9b1f8e2a-7b31-7c4e-9a1d-2f3b4c5d6e7f",
    "name": "Campanha X",
    "message": "Oferta: {meu_link}",
    "status": "sent_with_errors",
    "scheduled_date": null,
    "leads_count": 1500,
    "partner_reference": "ref-abc",
    "flash_sms": false,
    "concat": false,
    "from": null,
    "idempotency_key": "key-123",
    "created_at": "2026-06-30T14:00:00-03:00",
    "metrics": {
        "sent": 1450, // Mensagens que saíram para a operadora (entregues ou não)
        "failed": 50, // Mensagens que não saíram: canceladas ou bloqueadas (nada é cobrado)
        "total": 1500 // Total de mensagens
    },
    "delivery": {
        "delivered": 1200, // Entrega confirmada no aparelho
        "sent_to_carrier": 250, // Saíram, sem confirmação de entrega
        "total": 1450 // delivered + sent_to_carrier
    }
}
```

{% hint style="info" %}
Mensagens ainda na fila (`queued`) não entram em `sent` nem em `failed`, por isso `sent + failed` pode ser menor que `total` enquanto o broadcast está em andamento.
{% endhint %}

***

<mark style="color:green;">**GET**</mark>**&#x20;/sms/broadcasts/{id}/contacts**

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

**Parâmetros de query (opcionais):**

```json5
{
    "phone": "5511", // Busca por trecho do telefone
    "status": "delivered", // Filtra por status (ver tabela abaixo)
    "per_page": 50, // Itens por página. Padrão: 50. Mínimo: 1, Máximo: 200.
    "page": 1 // Página desejada
}
```

**Corpo de resposta — `200 OK`:**

```json5
{
    "current_page": 1,
    "data": [
        {
            "id": "0190c8e2-abab-7da9-9a46-4da50bd49147", // ID da mensagem (external_message_id)
            "reference": "order-123", // Sua referência
            "phone": "5511999999999", // Telefone
            "message": "Ola!", // Mensagem enviada ao contato
            "status": "delivered", // Status da mensagem
            "cancelled": false, // Indica se o envio foi cancelado
            "created_at": "2026-06-30T14:00:01-03:00",
            "sent_at": "2026-06-30T14:00:13-03:00" // Despacho para a operadora
        }
    ],
    "first_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/broadcasts/9b1i.../contacts?page=1",
    "from": 1,
    "next_page_url": null,
    "path": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/broadcasts/9b1i.../contacts",
    "per_page": 50,
    "prev_page_url": null,
    "to": 1
}
```

#### Tabela de status

{% hint style="info" %}
Esses são os mesmos valores aceitos no filtro ?status=. Qualquer outro valor retorna 422.
{% endhint %}

{% hint style="warning" %}
Cuidado com o ?status= na página de listagem de broadcasts. Esse filtro difere do **GET /sms/broadcasts** (a lista de broadcasts), o ?status= de lá aceita um vocabulário diferente: **pending, scheduled, sent, sent\_with\_errors, sending, sanitizing, importing, cancelled.** Os status aqui se refente a status de envio de cada lead entre processos internos e retornos da operadora.
{% endhint %}

| `status`           | Significado                                                         |
| ------------------ | ------------------------------------------------------------------- |
| queued             | Na fila, ainda não despachado                                       |
| sent\_to\_carrier  | Despachado da nossa fila para a operadora                           |
| delivered          | Entrega confirmada pela operadora                                   |
| blocked\_blacklist | Bloqueado por blacklist                                             |
| blocked\_content   | Bloqueado por política de conteúdo                                  |
| cancelled          | Não saiu: cancelamento seu, saldo insuficiente ou telefone inválido |

{% hint style="warning" %}
**sent\_to\_carrier** pode ser o estado final, pois nem todos os retornos podem chegar. Use delivered como confirmação positiva, mas não interprete sent\_to\_carrier como pendência que será resolvida — ela pode permanecer assim para sempre, mesmo tendo sido entregue.
{% endhint %}

{% hint style="info" %}
Mensagens enviadas antes de 12 de agosto de 2026 não possuem retorno da operadora e aparecem com status `queued`.
{% endhint %}

***

<mark style="color:green;">**GET**</mark>**&#x20;/sms/messages/{external\_message\_id}**

**Função:** Consulta o status de uma mensagem específica, pelo `id` retornado no envio. Também aceita o `id` de mensagens disparadas por sequências (campanhas) — nesse caso, `reference` vem `null`.

**Corpo de resposta — `200 OK`:**

```json5
{
    "id": "0190c8e2-abab-7da9-9a46-4da50bd49147", // ID da mensagem (external_message_id)
    "reference": "order-123", // Sua referência
    "phone": "5511999999999", // Telefone
    "status": "delivered", // Status da mensagem
    "sent_at": "2026-06-30T14:00:05-03:00" // Data de envio (ou nulo)
}
```

***

<mark style="color:green;">**GET**</mark>**&#x20;/sms/messages/{external\_message\_id}/replies**

**Função:** Lista as respostas (SMS recebidos) do destinatário a uma mensagem de broadcast, da mais recente para a mais antiga. Funciona para mensagens enviadas por `POST /sms/messages`; para mensagens de sequência, a resposta é `404`.

**Parâmetros de query (opcionais):**

```json5
{
    "per_page": 50, // Itens por página. Padrão: 50. Mínimo: 1, Máximo: 200.
    "page": 1 // Página desejada
}
```

**Corpo de resposta — `200 OK`:**

```json5
{
    "current_page": 1,
    "data": [
        {
            "id": "0190c8f1-1a2b-7c3d-9e4f-5a6b7c8d9e0f", // ID da resposta
            "phone": "5511999999999", // Telefone que respondeu
            "message": "Quero saber mais", // Texto recebido
            "received_at": "2026-06-30T14:05:10-03:00" // Data/hora do recebimento
        }
    ],
    "first_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/messages/0190c8e2-.../replies?page=1",
    "from": 1,
    "next_page_url": null,
    "path": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/messages/0190c8e2-.../replies",
    "per_page": 50,
    "prev_page_url": null,
    "to": 1
}
```

***

<mark style="color:blue;">**PUT**</mark>**&#x20;/sms/broadcasts/{id}/cancel**

**Função:** Cancela um broadcast. Apenas broadcasts nos status `pending`, `scheduled` ou `sending` podem ser cancelados. Logo após o envio, o broadcast passa por `sanitizing`/`importing` — nesses status o cancelamento retorna `409`; aguarde alguns segundos e tente novamente.

**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"`).

```json5
{
    "id": "9b1f8e2a-7b31-7c4e-9a1d-2f3b4c5d6e7f",
    "name": "Campanha X",
    "message": "...",
    "status": "cancelled",
    "scheduled_date": "2026-07-01T10:00:00-03:00",
    "leads_count": 1500,
    "partner_reference": "ref-abc",
    "flash_sms": false,
    "concat": true,
    "from": "LOJA",
    "idempotency_key": "key-123",
    "created_at": "2026-06-30T14:00:00-03:00",
    "cancellation": "complete" // "complete" (200) ou "partial" (202)
}
```

{% hint style="warning" %}
Broadcasts em qualquer outro status — em preparação (`sanitizing`, `importing`), finalizados (`sent`, `sent_with_errors`) ou já cancelados (`cancelled`) — retornam `409 INVALID_STATUS_TRANSITION`, com o status atual em `details.current_status`.
{% endhint %}

***

#### Código de Erros Comuns

* `401 Unauthorized` / `403 Forbidden`: Problema com a Chave de API (veja Autenticação).
* `402 Payment Required` (`INSUFFICIENT_CREDITS`): Créditos de SMS insuficientes para o envio. Só para contas no pacote de créditos.
* `403 Forbidden` (`OUTSIDE_SEND_WINDOW`): Envio ou agendamento fora da janela de 07:00 às 22:00 (horário de Brasília).
* `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.
* `409 Conflict` (`BROADCAST_INTERVAL_NOT_RESPECTED`): O disparo não respeita o intervalo mínimo exigido pela sua conta. Detalhes em `details` (`interval_minutes`, `requested_schedule`, `conflicting_schedule`).
* `422 Unprocessable Entity` (`VALIDATION_ERROR`): Algum campo do corpo da requisição é inválido (inclui `{meu_link}` sem `url`, `Idempotency-Key` acima de 80 caracteres e `status` inválido no filtro de contatos).
* `429 Too Many Requests` (`RATE_LIMIT_EXCEEDED`): Limite de requisições por minuto excedido (padrão: **60 por minuto por conta**). 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:**

```json5
{
    "error": {
        "code": "INVALID_STATUS_TRANSITION", // Código do erro
        "message": "Broadcast cannot be cancelled in its current status.", // Descrição
        "details": { // Opcional: detalhes adicionais
            "current_status": "sent"
        }
    }
}
```

**Dúvidas?**

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