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

# Sequências

As **Sequências** são os passos que compõem uma campanha. Cada sequência pode ser uma **mensagem de SMS** ou uma **ligação de voz**, e define o intervalo de envio em relação à entrada do lead na lista. Através destes endpoints você pode listar, criar, consultar, atualizar e remover sequências de uma campanha, e acompanhar o resultado das ligações de uma sequência de voz.

{% 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 de Sequências retornam um **array direto** (sem envelope `data` e sem paginação). Os endpoints de recurso único retornam um **objeto direto**. A exceção é `GET /sms/sequences/{id}/calls`, que é paginado.
{% endhint %}

***

**Tipos de sequência**

Toda sequência traz o campo **`type`**, que indica o canal:

| `type`  | Canal         | Campos específicos                                             |
| ------- | ------------- | -------------------------------------------------------------- |
| `sms`   | SMS           | `text`, `url`, `short_url`                                     |
| `call`  | Ligação (voz) | `audio_id`, `call_max_attempts`, `call_retry_interval_minutes` |
| `other` | Outro canal   | Existe no painel, mas não pode ser criado pela API             |

{% hint style="info" %}
Na criação, se o `type` não for informado, a sequência é criada como **`sms`**. Integrações que já existiam continuam funcionando sem nenhuma alteração.
{% endhint %}

**Fluxo para uma sequência de voz**

```
1. POST /calls/audios                                → envia o áudio             (audio_id)
2. GET  /calls/audios/{id}                           → aguarda "ready": true
3. POST /sms/campaigns/{campaign_id}/sequences       → cria a sequência de voz   (type: "call")
4. POST /lists/{id}/leads                            → lead entra na lista e a ligação é agendada
5. GET  /sms/sequences/{id}/calls                    → resultado de cada ligação
```

***

**Endpoints**

<mark style="color:green;">**GET**</mark>**&#x20;/sms/sequences/interval-types**

**Função:** Lista os tipos de intervalo disponíveis, para uso no campo `interval_type_id`.

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

```json5
[
    { "id": 1, "name": "MINUTE", "type": "MINUTE", "label": "Minuto(s)" },
    { "id": 2, "name": "HOUR",   "type": "HOUR",   "label": "Hora(s)" },
    { "id": 3, "name": "DAY",    "type": "DAY",    "label": "Dia(s)" },
    { "id": 4, "name": "WEEK",   "type": "WEEK",   "label": "Semana(s)" },
    { "id": 5, "name": "MONTH",  "type": "MONTH",  "label": "Mês(ses)" }
]
```

***

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

**Função:** Lista todas as sequências de uma campanha, ordenadas pela posição. Sequências de SMS e de voz vêm na mesma lista. Use o campo `type` para diferenciá-las.

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

```json5
[
    {
        "id": "0190c8e2-7b31-7c4e-9a1d-2f3b4c5d6e7f", // ID da sequência
        "campaign_id": "0190aaaa-1111-7c4e-9a1d-aaaabbbbcccc", // ID da campanha
        "type": "sms", // Canal: "sms", "call" ou "other"
        "interval": 1, // Intervalo
        "interval_type_id": 3, // Tipo de intervalo (3 = Dia)
        "position": 1, // Posição na sequência
        "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-30T12:00:00-03:00",
        "updated_at": "2026-06-30T12:00:00-03:00"
    },
    {
        "id": "0190c8e2-9999-7c4e-9a1d-1234567890ab",
        "campaign_id": "0190aaaa-1111-7c4e-9a1d-aaaabbbbcccc",
        "type": "call", // Sequência de voz
        "interval": 5,
        "interval_type_id": 1, // 1 = Minuto
        "position": 2,
        "text": null, // Sempre nulo em sequência de voz
        "active": true,
        "url": null, // Sempre nulo em sequência de voz
        "short_url": null, // Sempre nulo em sequência de voz
        "created_at": "2026-06-30T12:00:00-03:00",
        "updated_at": "2026-06-30T12:00:00-03:00",
        "audio_id": "0190bbbb-2222-7c4e-9a1d-ddddeeeeffff", // Áudio tocado na ligação
        "call_max_attempts": 3, // Tentativas de discagem por lead
        "call_retry_interval_minutes": 30 // Minutos entre uma tentativa e outra
    }
]
```

{% hint style="info" %}
Os campos `audio_id`, `call_max_attempts` e `call_retry_interval_minutes` só aparecem em sequências com `"type": "call"`.
{% endhint %}

***

<mark style="color:green;">**POST**</mark>**&#x20;/sms/campaigns/{campaign\_id}/sequences**

**Função:** Cria uma nova sequência dentro de uma campanha. A `position` é atribuída automaticamente (sempre ao final). O corpo muda conforme o `type`.

{% tabs %}
{% tab title="SMS" %}
**Corpo de envio:**

```json5
{
    "type": "sms", // Opcional. Padrão: "sms".
    "interval": 2, // Obrigatório. Inteiro >= 1.
    "interval_type_id": 2, // Obrigatório. 1=Minuto, 2=Hora, 3=Dia, 4=Semana, 5=Mês.
    "text": "Promo: {meu_link}", // Obrigatório. 1 a 1600 caracteres.
    "active": true, // Opcional. Padrão: true.
    "url": "https://example.com/promo" // Opcional. Obrigatório quando o texto contém {meu_link}.
}
```

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

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

```json5
{
    "id": "0190c8e2-7b31-7c4e-9a1d-2f3b4c5d6e7f",
    "campaign_id": "0190aaaa-1111-7c4e-9a1d-aaaabbbbcccc",
    "type": "sms",
    "interval": 2,
    "interval_type_id": 2,
    "position": 2,
    "text": "Promo: {meu_link}",
    "active": true,
    "url": "https://example.com/promo",
    "short_url": "https://go.site/abc123",
    "created_at": "2026-06-30T12:05:00-03:00",
    "updated_at": "2026-06-30T12:05:00-03:00"
}
```

{% endtab %}

{% tab title="Ligação (voz)" %}
**Corpo de envio:**

```json5
{
    "type": "call", // Obrigatório para sequência de voz.
    "interval": 5, // Obrigatório. Inteiro >= 1.
    "interval_type_id": 1, // Obrigatório. 1=Minuto, 2=Hora, 3=Dia, 4=Semana, 5=Mês.
    "audio_id": "0190bbbb-2222-7c4e-9a1d-ddddeeeeffff", // Obrigatório. ID de um áudio seu, já processado.
    "call_max_attempts": 3, // Opcional. De 1 a 5. Padrão: 3.
    "call_retry_interval_minutes": 30, // Opcional. De 1 a 120. Padrão: 30.
    "active": true // Opcional. Padrão: true.
}
```

{% hint style="warning" %}
O áudio precisa estar **processado** antes de ser usado. Após o `POST /calls/audios`, consulte o áudio e aguarde `"ready": true`. Se ele ainda estiver em processamento, a criação retorna `422` com o código `AUDIO_NOT_READY`.
{% endhint %}

{% hint style="warning" %}
Os campos `text` e `url` **não são aceitos** em sequência de voz. Se forem enviados, a requisição retorna `422`.
{% endhint %}

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

```json5
{
    "id": "0190c8e2-9999-7c4e-9a1d-1234567890ab",
    "campaign_id": "0190aaaa-1111-7c4e-9a1d-aaaabbbbcccc",
    "type": "call",
    "interval": 5,
    "interval_type_id": 1,
    "position": 2,
    "text": null,
    "active": true,
    "url": null,
    "short_url": null,
    "created_at": "2026-06-30T12:05:00-03:00",
    "updated_at": "2026-06-30T12:05:00-03:00",
    "audio_id": "0190bbbb-2222-7c4e-9a1d-ddddeeeeffff",
    "call_max_attempts": 3,
    "call_retry_interval_minutes": 30
}
```

{% endtab %}
{% endtabs %}

***

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

**Função:** Obtém os detalhes de uma sequência específica. O formato é o mesmo de um item da listagem: sequências de voz trazem também `audio_id`, `call_max_attempts` e `call_retry_interval_minutes`.

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

```json5
{
    "id": "0190c8e2-7b31-7c4e-9a1d-2f3b4c5d6e7f",
    "campaign_id": "0190aaaa-1111-7c4e-9a1d-aaaabbbbcccc",
    "type": "sms",
    "interval": 2,
    "interval_type_id": 2,
    "position": 2,
    "text": "Promo: {meu_link}",
    "active": true,
    "url": "https://example.com/promo",
    "short_url": "https://go.site/abc123",
    "created_at": "2026-06-30T12:05:00-03:00",
    "updated_at": "2026-06-30T12:05:00-03:00"
}
```

***

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

**Função:** Atualiza uma sequência. Todos os campos são opcionais, e apenas os enviados serão alterados. Os campos aceitos dependem do `type` da sequência.

{% tabs %}
{% tab title="SMS" %}
**Corpo de envio:**

```json5
{
    "interval": 3, // Opcional. Inteiro >= 1.
    "interval_type_id": 3, // Opcional. 1=Minuto, 2=Hora, 3=Dia, 4=Semana, 5=Mês.
    "text": "Ola {first_name}, confira: {meu_link}", // Opcional. 1 a 1600 caracteres.
    "active": false, // Opcional. Boolean.
    "url": "https://example.com/nova-promo" // Opcional. Envie null para remover o link.
}
```

{% endtab %}

{% tab title="Ligação (voz)" %}
**Corpo de envio:**

```json5
{
    "interval": 10, // Opcional. Inteiro >= 1.
    "interval_type_id": 1, // Opcional. 1=Minuto, 2=Hora, 3=Dia, 4=Semana, 5=Mês.
    "audio_id": "0190bbbb-3333-7c4e-9a1d-111122223333", // Opcional. Troca o áudio (precisa estar processado).
    "call_max_attempts": 2, // Opcional. De 1 a 5.
    "call_retry_interval_minutes": 60, // Opcional. De 1 a 120.
    "active": false // Opcional. Boolean.
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
O **`type` não pode ser alterado**. Para trocar o canal, remova a sequência e crie outra. Enviar campos de SMS (`text`, `url`) numa sequência de voz, ou campos de voz (`audio_id`, `call_max_attempts`, `call_retry_interval_minutes`) numa sequência de SMS, retorna `422`.
{% endhint %}

{% hint style="info" %}
A `position` da sequência **não** é alterável por este endpoint. A regra do `{meu_link}` ⇄ `url` também se aplica aqui, considerando os valores efetivos (campos enviados + valores atuais).
{% endhint %}

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

***

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

**Função:** Remove uma sequência.

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

***

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

**Função:** Lista as ligações de uma sequência de voz, com o resultado de cada uma: se atendeu, se escutou até o fim, se digitou uma tecla ou se não atendeu. Funciona apenas para sequências com `"type": "call"`.

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

```json5
{
    "page": 1, // Página desejada (paginação simples)
    "per_page": 50, // Itens por página. Padrão: 50. Mínimo: 1, Máximo: 1000 (valores acima são ajustados).
    "pagination": "cursor", // Opcional. Ativa a paginação por cursor (recomendada para sequências grandes)
    "cursor": "eyJwaG9uZSI6...", // Cursor da próxima página (valor de next_cursor)
    "status": "answered_dtmf", // Filtra por resultado (veja a tabela abaixo). Valor desconhecido é ignorado
    "phone": "11987654321" // Filtra por telefone (busca parcial)
}
```

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

```json5
{
    "current_page": 1,
    "data": [
        {
            "id": "01a0d1f2-9c3e-7a41-8b2d-5e6f7a8b9c0d", // ID da ligação
            "phone": "11987654321", // Telefone
            "name": "Maria Souza", // Nome do lead (ou nulo)
            "status": "answered_dtmf", // Resultado (valor fixo, use este para programar)
            "status_label": "Atendida com Digitação", // Resultado em texto, igual ao painel
            "pabx_status": "ANSWER", // Status bruto da central telefônica
            "call_duration_seconds": 18, // Duração em segundos (ou nulo)
            "listened_percentage": 72.5, // Percentual do áudio ouvido (ou nulo)
            "dtmf_response": "1", // Tecla digitada (ou nulo)
            "tries": 1, // Tentativa atual
            "max_attempts": 3, // Tentativas configuradas
            "sent_at": "2026-09-24T10:15:02-03:00", // Quando a ligação foi disparada
            "answered_at": "2026-09-24T10:15:31-03:00" // Quando recebemos o resultado da ligação
        }
    ],
    "first_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/sequences/0190c8e2-9999-7c4e-9a1d-1234567890ab/calls?page=1",
    "from": 1,
    "next_page_url": null,
    "path": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/sequences/0190c8e2-9999-7c4e-9a1d-1234567890ab/calls",
    "per_page": 50,
    "prev_page_url": null,
    "to": 1
}
```

{% hint style="info" %}
Os resultados são ordenados por telefone. Há dois modos de paginação, sem campos `total` ou `last_page`:

* **Simples (padrão):** avance incrementando `page` até `next_page_url` vir nulo, e **reenvie `per_page` e `status` em todas as páginas**, porque o `next_page_url` leva apenas o `page`.
* **Por cursor (recomendado para sequências grandes):** envie `pagination=cursor` na primeira página. A resposta traz `next_cursor`; envie-o em `cursor` para buscar a próxima página, até ele vir nulo. Nesse modo o `next_page_url` já carrega todos os filtros. Um cursor inválido retorna `422 INVALID_CURSOR`.
  {% endhint %}

{% hint style="info" %}
Uma ligação com `status: "no_answer"` ainda pode ser tentada de novo: o resultado só é definitivo quando `tries` é igual a `max_attempts`.
{% endhint %}

{% hint style="warning" %}
Se a sequência consultada for de SMS, a resposta é `409 Conflict` com o código `INVALID_SEQUENCE_TYPE`.
{% endhint %}

**Resultados possíveis da ligação**

| `status`            | `status_label`           | Significado                                                      |
| ------------------- | ------------------------ | ---------------------------------------------------------------- |
| `waiting`           | Aguardando               | A ligação ainda não foi feita ou ainda não recebemos o resultado |
| `no_answer`         | Recusada / Não Atendida  | Não atendeu, deu ocupado, recusou ou não foi possível completar  |
| `answered_hangup`   | Atendida e Desligada     | Atendeu e desligou antes do fim do áudio (ouviu menos de 95%)    |
| `answered_listened` | Escutou até o Fim        | Atendeu e escutou 95% ou mais do áudio                           |
| `answered_dtmf`     | Atendida com Digitação   | Atendeu e digitou uma tecla (veja `dtmf_response`)               |
| `cancelled`         | Cancelado                | Ligação cancelada                                                |
| `error`             | Erro / Telefone inválido | Não foi possível discar para o número                            |

***

**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, a sequência ou o áudio não foi encontrado ou não pertence à sua conta.
* `409 Conflict` (`INVALID_SEQUENCE_TYPE`): O endpoint de ligações (`/calls`) foi chamado para uma sequência que não é de voz.
* `422 Unprocessable Entity` (`VALIDATION_ERROR`): Algum campo do corpo da requisição é inválido. Inclui `{meu_link}` sem `url` (ou `url` sem `{meu_link}` no texto), campo de SMS numa sequência de voz (ou o contrário), e tentativa de alterar o `type`.
* `422 Unprocessable Entity` (`AUDIO_NOT_READY`): O áudio informado ainda não terminou de ser processado.
* `422 Unprocessable Entity` (`INVALID_CURSOR`): O `cursor` enviado em `/calls` é inválido. Use o `next_cursor` devolvido pela página anterior.

**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)
            "url": [
                "O campo url é obrigatório quando a mensagem contém a TAG {meu_link}."
            ]
        }
    }
}
```

**Exemplo — áudio ainda em processamento:**

```json5
{
    "error": {
        "code": "AUDIO_NOT_READY",
        "message": "O áudio ainda não terminou de ser processado. Consulte GET /parceiros/v1/calls/audios e aguarde `ready: true`.",
        "details": {
            "audio_status": "processing"
        }
    }
}
```

**Dúvidas?**

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