> 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/campanhas.md).

# Campanhas

As **Campanhas** definem fluxos automatizados de mensagens (sequências) disparados aos leads de uma lista. Através destes endpoints você pode criar, consultar, atualizar e remover suas campanhas.

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

{% hint style="info" %}
O endpoint de listagem utiliza **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 %}

***

#### Endpoints

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

**Função:** Lista todas as suas campanhas, da mais recente para a mais antiga.

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

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

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

```json5
{
    "current_page": 1,
    "data": [
        {
            "id": "018f9c2a-7b31-7c4e-9a1d-2f3b4c5d6e7f", // ID da campanha
            "name": "Black Friday", // Nome da campanha
            "active": true, // Indica se a campanha está ativa
            "lead_list_id": "018f9c2a-1111-7c4e-9a1d-aaaabbbbcccc", // ID da lista vinculada
            "created_at": "2026-06-30T14:05:00+00:00", // Data de criação
            "updated_at": "2026-06-30T14:05:00+00:00" // Data da última atualização
        }
    ],
    "first_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/campaigns?page=1",
    "from": 1,
    "next_page_url": null,
    "path": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/campaigns",
    "per_page": 20,
    "prev_page_url": null,
    "to": 1
}
```

{% hint style="info" %}
A listagem **não** retorna o detalhamento das sequências. Para obter as sequências de uma campanha, utilize o endpoint de consulta individual (`GET /sms/campaigns/{id}`).
{% endhint %}

***

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

**Função:** Cria uma nova campanha. Caso não informe `lead_list_id`, uma lista própria será criada e vinculada automaticamente (com o nome `Partner Campaign — <name>`). As sequências — de SMS e de voz — podem ser criadas junto, no mesmo corpo da requisição.

**Corpo de envio:**

```json5
{
    "name": "Black Friday", // Obrigatório. String de 1 a 50 caracteres.
    "active": true, // Opcional. Padrão: true.
    "lead_list_id": "018f9c2a-1111-7c4e-9a1d-aaaabbbbcccc", // Opcional. ID de uma lista sua. Se omitido, criamos uma lista automaticamente.
    "sequences": [ // Opcional. Até 50 sequências.
        {
            "interval": 1, // Obrigatório (se houver sequências). Inteiro >= 1.
            "interval_type_id": 3, // Obrigatório. 1=Minuto, 2=Hora, 3=Dia, 4=Semana, 5=Mês.
            "text": "Ola {first_name}, confira {meu_link}", // Obrigatório. 1 a 1530 caracteres.
            "active": true, // Opcional. Padrão: true.
            "url": "https://example.com/promo" // Opcional. Obrigatório quando o texto contém {meu_link}.
        },
        {
            "type": "call", // Opcional. "sms" (padrão) ou "call" (ligação de voz)
            "interval": 2, // Obrigatório.
            "interval_type_id": 3, // Obrigatório.
            "audio_id": "0192e456-7b31-7c4e-9a1d-2f3b4c5d6e7f", // Obrigatório em "call". Áudio seu, já processado (ready: true)
            "call_max_attempts": 3, // Opcional. 1 a 5. Padrão: 3
            "call_retry_interval_minutes": 30 // Opcional. 1 a 120. Padrão: 30
        }
    ]
}
```

{% hint style="warning" %}
**Envie as sequências na criação.** Se `sequences` for omitido, a campanha é criada com **4 sequências de SMS em branco** (15 minutos, 2 dias, 1 semana e 1 mês), sem texto. Elas não enviam nada, mas aparecem nas consultas. Para removê-las, use `DELETE /sms/sequences/{id}`.
{% endhint %}

{% hint style="info" %}
Em sequências de voz, `text` e `url` não são aceitos. Um `audio_id` que não existe ou não é da sua conta retorna `422 VALIDATION_ERROR` (no campo `sequences.N.audio_id`); um áudio ainda em processamento retorna `422 AUDIO_NOT_READY`. Veja Sequências e Ligações - Áudios.
{% endhint %}

{% hint style="warning" %}
Quando o texto de uma sequência contém a variável `{meu_link}`, o campo `url` é **obrigatório** naquela sequência (e vice-versa). Nós encurtamos o link automaticamente e o retornamos em `short_url`.
{% endhint %}

**Corpo de resposta — `201 Created`:**

```json5
{
    "id": "018f9c2a-7b31-7c4e-9a1d-2f3b4c5d6e7f",
    "name": "Black Friday",
    "active": true,
    "lead_list_id": "018f9c2a-1111-7c4e-9a1d-aaaabbbbcccc",
    "created_at": "2026-06-30T14:05:00+00:00",
    "updated_at": "2026-06-30T14:05:00+00:00",
    "sequences": [
        {
            "id": "018f9c2a-9999-7c4e-9a1d-1234567890ab", // ID da sequência
            "campaign_id": "018f9c2a-7b31-7c4e-9a1d-2f3b4c5d6e7f", // ID da campanha
            "interval": 1, // Intervalo
            "interval_type_id": 3, // Tipo de intervalo (3 = Dia)
            "position": 1, // Posição na sequência
            "type": "sms", // Canal da sequência: "sms" ou "call"
            "text": "Ola {first_name}, confira {meu_link}", // Texto da mensagem
            "active": true, // Sequência ativa
            "url": "https://example.com/promo", // Link "Meu Link" (ou nulo)
            "short_url": "https://go.site/abc123", // Link encurtado (ou nulo)
            "created_at": "2026-06-30T14:05:00+00:00",
            "updated_at": "2026-06-30T14:05:00+00:00"
        }
    ]
}
```

***

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

**Função:** Obtém os detalhes de uma campanha específica, incluindo suas sequências.

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

```json5
{
    "id": "018f9c2a-7b31-7c4e-9a1d-2f3b4c5d6e7f",
    "name": "Black Friday",
    "active": true,
    "lead_list_id": "018f9c2a-1111-7c4e-9a1d-aaaabbbbcccc",
    "created_at": "2026-06-30T14:05:00+00:00",
    "updated_at": "2026-06-30T14:05:00+00:00",
    "sequences": [
        {
            "id": "018f9c2a-9999-7c4e-9a1d-1234567890ab",
            "campaign_id": "018f9c2a-7b31-7c4e-9a1d-2f3b4c5d6e7f",
            "interval": 1,
            "interval_type_id": 3,
            "position": 1,
            "text": "Ola {first_name}, confira {meu_link}",
            "active": true,
            "url": "https://example.com/promo",
            "short_url": "https://go.site/abc123",
            "created_at": "2026-06-30T14:05:00+00:00",
            "updated_at": "2026-06-30T14:05:00+00:00"
        }
    ]
}
```

***

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

**Função:** Atualiza uma campanha. Apenas os campos `name` e `active` podem ser alterados.

**Corpo de envio:**

```json5
{
    "name": "Black Friday 2026", // Opcional. Se informado, 1 a 50 caracteres.
    "active": false // Opcional. Boolean.
}
```

{% hint style="warning" %}
Os campos `lead_list_id` e `sequences` **não** podem ser enviados neste endpoint — o envio retornará `422 VALIDATION_ERROR`. A lista e as sequências são definidas apenas na criação da campanha.
{% endhint %}

**Corpo de resposta — `200 OK`:** mesmo formato do `GET /sms/campaigns/{id}`.

***

<mark style="color:red;">**DELETE**</mark>**&#x20;/sms/campaigns/{id}**

**Função:** Remove uma campanha. As sequências vinculadas são removidas automaticamente em cascata. A lista vinculada (inclusive a criada automaticamente) **não** é removida.

**Corpo de resposta:** `204 No Content` (sem corpo).

***

<mark style="color:green;">**POST**</mark>**&#x20;/sms/campaigns/{id}/leads**

**Função:** Insere um lote de leads na lista vinculada à campanha e agenda as sequências dela. É um atalho para `POST /lists/{id}/leads` quando você conhece a campanha e não a lista.

**Corpo de envio:** o mesmo de `POST /lists/{id}/leads` (1 a 500 leads com `phone`, `name`, `email`, `custom_fields` e `customized_url`). O `customized_url` alimenta a variável `{url_lista}` com as mesmas regras, inclusive o cancelamento da mensagem quando a sequência usa `{url_lista}` e o lead vem sem link. Aceita o header `Idempotency-Key` com as mesmas regras.

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

```json5
{
    "accepted_count": 2, // Leads aceitos e enfileirados
    "blacklisted_count": 1, // Leads inseridos, porém na blacklist (não disparam sequências)
    "leads": [
        { "lead_id": "018f8e2a-...-1", "status": "accepted", "blacklisted": false },
        { "lead_id": "018f8e2a-...-2", "status": "accepted", "blacklisted": false },
        { "lead_id": "018f8e2a-...-3", "status": "blacklisted", "blacklisted": true }
    ]
}
```

{% hint style="info" %}
Se a campanha estiver **inativa** (`active: false`), os leads são gravados na lista, mas nenhuma sequência é agendada. A inserção não confere saldo; ele é conferido no momento de cada envio (veja Saldo e Carteira).
{% endhint %}

***

#### Tabela de tipos de intervalo

| `interval_type_id` | Tipo   |
| ------------------ | ------ |
| 1                  | Minuto |
| 2                  | Hora   |
| 3                  | Dia    |
| 4                  | Semana |
| 5                  | Mês    |

***

#### Código de Erros Comuns

* `401 Unauthorized` / `403 Forbidden`: Problema com a Chave de API (veja Autenticação).
* `404 Not Found` (`NOT_FOUND`): A campanha (ou a lista informada em `lead_list_id`) não foi encontrada ou não pertence à sua conta.
* `409 Conflict` (`CONCURRENT_REQUEST`): Já existe uma inserção de leads em processamento com o mesmo `Idempotency-Key`.
* `422 Unprocessable Entity` (`VALIDATION_ERROR`): Algum campo do corpo da requisição é inválido (inclui enviar `lead_list_id`/`sequences` no `PUT`, `{meu_link}` sem `url`, ou `audio_id` que não é seu).
* `422 Unprocessable Entity` (`AUDIO_NOT_READY`): O áudio de uma sequência de voz ainda não terminou de ser processado.
* `500 Internal Server Error` (`INTERNAL_ERROR`): Ocorreu um erro interno ao processar a requisição.

**Corpo de resposta de erro:**

```json5
{
    "error": {
        "code": "VALIDATION_ERROR", // Código do erro
        "message": "The given data was invalid.", // Descrição
        "details": { // Opcional: detalhes por campo (presente em erros de validação)
            "name": [
                "Field `name` is required."
            ]
        }
    }
}
```

**Dúvidas?**

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