> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useintegra.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar campanha

> Dispare uma campanha de ligações ou de mensagens de WhatsApp

## Canais

O campo `channel` decide o tipo de campanha. Ele é opcional e vale `voice` quando você não envia.

| Canal | O que faz | Campos obrigatórios além dos comuns |
| - | - | - |
| `voice` | Liga para a lista com um agente de voz | `agent_id`, `phone_number_id` |
| `whatsapp` | Dispara um template aprovado pela Meta | `template_name` |

Os campos comuns aos dois canais são `name`, `project_id`, `scheduled_at` e `recipients`.

> [!NOTE]
>
> No canal `voice`, `scheduled_at` precisa ser no futuro. No canal `whatsapp`, uma data no passado é aceita e dispara no próximo ciclo do worker: é assim que você agenda um "enviar agora".

> [!WARNING]
>
> **Fuso do `scheduled_at` nas campanhas de voz.** A API exige data, hora e fuso; sem o fuso, ou só com a data, a resposta é `400`. O sufixo `Z` quer dizer UTC de verdade: `2026-09-01T14:00:00Z` disca às **11:00 de São Paulo**. Para discar às 14:00 de São Paulo, envie `2026-09-01T14:00:00-03:00`. As respostas das campanhas de voz trazem os horários de São Paulo, com `-03:00`.

## Campanha de WhatsApp

### Variáveis do template

O corpo do template usa marcadores numerados: `Oi {{1}}, seu horário é {{2}}`. Cada destinatário preenche esses marcadores pelo `dynamic_variables`, com **chaves numéricas em texto**:

```json theme={null}
{
  "phone_number": "+5511999999999",
  "recipient_name": "Ana",
  "dynamic_variables": { "1": "Ana", "2": "quinta às 14h" }
}
```

A chave `"n"` preenche o `{{n}}` do corpo. O que vale é a posição.

Chaves com nome, como `leadName` ou `empresa`, também são aceitas no WhatsApp, mas não entram na mensagem: são dados do contato para o agente de texto que atende quem responder, como no canal `voice`. Para escolher esse agente, envie `agent_id` com o id de um agente de texto; sem ele, vale o agente ligado ao template.

> [!WARNING]
>
> A quantidade de chaves numéricas de **cada** destinatário tem que bater com o número de `{{n}}` do corpo. Faltando ou sobrando, a campanha inteira é recusada com `422` antes de qualquer disparo, e nenhuma mensagem é enviada. Confira o corpo do template no painel, em **Templates**.

### Antes de criar

Cada número de WhatsApp tem um limite de conversas que pode iniciar em 24h, definido pela Meta. Uma lista maior que o disponível é recusada com `422`. Consulte [as conversas disponíveis](https://docs.useintegra.com.br/api-reference/endpoint/campaigns-quota.md) antes de montar a lista.

## Exemplos

```bash Campanha de WhatsApp theme={null}
curl -X POST https://api.useintegra.com.br/api/v1/campaigns \
  -H "Authorization: Bearer ik_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retomada de matrículas",
    "project_id": "proj_abc123",
    "channel": "whatsapp",
    "template_name": "retomada_matricula",
    "meta_phone_external_id": "1046702081862213",
    "scheduled_at": "2026-09-01T14:00:00Z",
    "recipients": [
      {
        "phone_number": "+5511999999999",
        "recipient_name": "Ana",
        "dynamic_variables": { "1": "Ana", "2": "quinta às 14h" }
      },
      {
        "phone_number": "+5521988887777",
        "recipient_name": "Bruno",
        "dynamic_variables": { "1": "Bruno", "2": "sexta às 10h" }
      }
    ]
  }'
```

```bash Campanha de voz theme={null}
curl -X POST https://api.useintegra.com.br/api/v1/campaigns \
  -H "Authorization: Bearer ik_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Confirmação de consulta",
    "project_id": "proj_abc123",
    "agent_id": "agt_xyz789",
    "phone_number_id": "phn_456def",
    "scheduled_at": "2026-09-01T14:00:00-03:00",
    "recipients": [
      {
        "phone_number": "+5511999999999",
        "recipient_name": "Ana",
        "dynamic_variables": { "leadName": "Ana" }
      }
    ],
    "config": {
      "call_timeout": 45,
      "voicemail_mode": "hangup",
      "max_concurrent": 2
    }
  }'
```

```json Resposta 201 theme={null}
{
  "id": "cmp_9f8e7d",
  "name": "Retomada de matrículas",
  "status": "PENDING",
  "channel": "whatsapp",
  "template_name": "retomada_matricula",
  "scheduled_at": "2026-09-01T14:00:00.000Z",
  "agent": null,
  "phone_number": null,
  "config": null,
  "total_recipients": 2,
  "created_at": "2026-08-17T10:32:00.000Z"
}
```

> [!NOTE]
>
> Campanhas de WhatsApp respondem com `agent`, `phone_number` e `config` nulos: elas não têm agente de voz, número de origem próprio nem parâmetros de discagem.

## Limites

| Campo | Teto |
| - | - |
| `name` | 200 caracteres |
| `project_id`, `agent_id`, `phone_number_id`, `scheduled_at` | 64 caracteres |
| `template_name` | 512 caracteres |
| `meta_phone_external_id` | 100 caracteres |
| `recipients` | 10.000 destinatários. Acima disso, a requisição volta com `400` sem validar os destinatários um a um |
| `recipient_name` | 200 caracteres |
| `dynamic_variables` | 50 chaves por destinatário; cada chave com até 100 caracteres e cada valor com até 1.000. Acima de 50 chaves, a requisição volta com `400` sem validar as chaves uma a uma |
| Corpo inteiro da requisição | 10 MB |

> [!NOTE]
>
> Os tetos por campo e o teto do corpo valem juntos. Uma lista de 10.000 destinatários com poucas variáveis curtas cabe com folga: um destinatário típico tem menos de 200 bytes. Com muitas variáveis longas, a lista passa de 10 MB antes de chegar a 10.000 destinatários e a resposta é `413`. Nesse caso, divida a lista em mais de uma campanha. Como referência, 10 MB dão cerca de 1 KB por destinatário numa lista de 10.000.

## Erros

| Status | Quando acontece | O que fazer |
| - | - | - |
| `400` | Payload inválido: campo obrigatório do canal ausente, `scheduled_at` fora do ISO 8601 (ou, no canal `voice`, sem fuso), mais de 10.000 destinatários, campo acima do teto, telefone fora do E.164 | Corrija o corpo. A mensagem aponta o campo; com muitos erros, ela traz os 10 primeiros e termina com `(and N more errors)` |
| `403` | A chave não tem o escopo que a rota exige (`Insufficient scope`), ou, no canal `voice`, o plano atingiu o teto mensal de ligações (`Monthly call limit reached (N/M)`) | Use uma chave com o escopo certo. No teto do plano, faça upgrade ou aguarde a virada do mês |
| `404` | Projeto ou template não encontrado na sua organização | Confira `project_id` e `template_name` no painel |
| `413` | Corpo da requisição acima de 10 MB (`Request body too large (max 10 MB)`). Nada é processado | Divida a lista em mais de uma campanha (veja **Limites**) |
| `422` | Template não aprovado ou desabilitado, variáveis que não batem com o corpo, ou lista maior que a quota de 24h | Veja os exemplos abaixo |
| `502` | Falha na comunicação com o serviço de WhatsApp | Leia o aviso abaixo antes de repetir |
| `503` | Canal `whatsapp`: integração de WhatsApp não configurada na sua organização | Conecte um número de WhatsApp no painel |
| `503` | Canal `voice`: não foi possível confirmar o teto mensal de ligações do plano (`Could not verify the plan's monthly call limit. Try again later.`). Nada é criado | Repita em alguns segundos, com espera crescente entre as tentativas |

### 422: variáveis que não batem com o corpo

A validação roda sobre a lista inteira e para no primeiro destinatário irregular. A mensagem diz quantas variáveis o corpo exige e qual número está errado:

```json theme={null}
{
  "error": "O template \"retomada_matricula\" usa 2 variavel(is) no corpo ({{1}}..{{2}}); a linha do numero +5511999999999 precisa de exatamente 2 valor(es) preenchido(s)."
}
```

### 422: quota de conversas excedida

```json theme={null}
{
  "error": "Seu numero pode iniciar 137 conversas nas proximas 24h (limite da Meta). Reduza a lista ou divida em dias."
}
```

> [!WARNING]
>
> **O `502` na criação não garante que a campanha deixou de ser criada.** A criação é gravada do outro lado em transação própria e pode ter sido concluída depois de estourar o tempo de resposta desta chamada.
>
> Antes de repetir a requisição, [liste suas campanhas](https://docs.useintegra.com.br/api-reference/endpoint/list-campaigns.md) e procure pelo `name` que você enviou. Repetir às cegas cria uma segunda campanha, e a lista inteira recebe o template duas vezes, consumindo quota da Meta em dobro. Não há como desfazer um disparo já entregue.


## OpenAPI

````yaml POST /api/v1/campaigns
openapi: 3.1.0
info:
  title: Integra BFI API
  version: 1.0.0
  description: >
    <img src="/public/logo_dark.webp" alt="Integra" height="36"
    style="margin-bottom:16px" />


    A API da Integra para integrações externas.


    > [!tip]

    > **Copie a documentação completa para sua IA favorita:**

    > [Abrir página de cópia](/docs/markdown) ou baixe o [llm.txt](/llm.txt)


    ---


    ## Como começar


    ### 1. Gerar sua API Key


    Acesse o painel da Integra em **Settings > API Keys** e clique em **Nova API
    Key**.


    > [!important]

    > Copie a key gerada (`ik_live_...`) imediatamente: ela **só será exibida
    uma vez**.


    ### 2. Autenticar requests


    Envie o header `Authorization` em todas as chamadas:


    ```

    Authorization: Bearer ik_live_sua_key_aqui

    ```


    ### 3. Fazer sua primeira chamada


    ```bash

    curl -H "Authorization: Bearer ik_live_xxx" \
      https://api.useintegra.com.br/api/v1/campaigns
    ```


    > [!success]

    > Se a resposta for `200 OK` com JSON, sua integração está funcionando!


    ---


    ## Rate Limiting


    | Header | Descrição |

    |--------|-----------|

    | `X-RateLimit-Limit` | Limite total (60/min) |

    | `X-RateLimit-Remaining` | Requests restantes |

    | `X-RateLimit-Reset` | Timestamp de reset (epoch) |


    > [!warning]

    > Ao exceder **60 requests/minuto** por API Key, a API retorna status `429
    Too Many Requests`.


    ---


    ## Erros comuns


    | Status | Erro | Causa |

    |--------|------|-------|

    | `401` | Invalid API key | Key inválida ou revogada |

    | `403` | Forbidden | Key sem permissão para o recurso |

    | `429` | Rate limit exceeded | Excedeu 60 req/min |

    | `500` | Internal server error | Erro interno, contate o suporte |
servers:
  - url: https://api.useintegra.com.br
    description: Production
security:
  - ApiKey: []
tags:
  - name: Campaigns
    description: Gerenciamento de campanhas de ligações
  - name: Calls
    description: Histórico de chamadas
  - name: Webhooks
    description: Gerenciamento de webhooks para notificações em tempo real
paths:
  /api/v1/campaigns:
    post:
      tags:
        - Campaigns
      summary: Criar nova campanha (voz ou WhatsApp)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                  example: Campanha Março 2026
                project_id:
                  type: string
                  maxLength: 64
                  description: Project ID (copy from Panel → project header)
                  example: b9c80a57-fad2-41a0-a304-727337ad1b1f
                channel:
                  type: string
                  enum:
                    - voice
                    - whatsapp
                  default: voice
                  description: >-
                    Campaign channel: voice (outbound calls, default) or
                    whatsapp (approved template broadcast)
                  example: voice
                agent_id:
                  type: string
                  maxLength: 64
                  description: >-
                    Agent ID (copy from Panel → agent card). Required for voice
                    campaigns (voice agent). Optional for WhatsApp: the text
                    agent that answers whoever replies (overrides the agent
                    linked to the template)
                  example: 7e09d093-904a-48de-ac49-b0445906c38e
                phone_number_id:
                  type: string
                  maxLength: 64
                  description: >-
                    Phone number ID assigned to the agent. Required for voice
                    campaigns
                  example: d1082e49-1b2c-4337-81e2-8eb74810351d
                template_name:
                  type: string
                  maxLength: 512
                  description: >-
                    Approved WhatsApp template name. Required for whatsapp
                    campaigns
                  example: boas_vindas_pt_br
                meta_phone_external_id:
                  type: string
                  maxLength: 100
                  description: >-
                    Meta phone number ID used as sender. Optional when the
                    organization has a single WhatsApp number
                  example: '109876543210987'
                scheduled_at:
                  type: string
                  maxLength: 64
                  description: >-
                    ISO 8601 date-time with timezone offset (Z, -0300 or
                    -03:00). Voice campaigns REQUIRE date, time and offset (400
                    without them), dial at this instant and are returned in São
                    Paulo time (-03:00). WhatsApp campaigns read a value without
                    offset as UTC and are returned in UTC (Z)
                  example: '2026-03-25T14:00:00-03:00'
                recipients:
                  type: array
                  items:
                    type: object
                    properties:
                      phone_number:
                        type: string
                        pattern: ^\+[1-9]\d{7,14}$
                        example: '+5511999999999'
                      recipient_name:
                        type: string
                        maxLength: 200
                        example: João Silva
                      dynamic_variables:
                        type: object
                        additionalProperties:
                          type: string
                          maxLength: 1000
                        description: >-
                          Key-value pairs for template variables (max 50 keys of
                          up to 100 characters; values up to 1000). Voice
                          campaigns accept free-form names used in the agent
                          prompt (e.g. leadName for {{leadName}}). WhatsApp
                          campaigns: numeric keys ("1", "2", ...) are the
                          positional template parameters ({{1}}, {{2}}); named
                          keys (e.g. leadName, empresa, email) are contact data
                          for the text agent that answers, the same logic as
                          voice (they go to the agent prompt, never to the
                          message)
                        example:
                          '1': João
                          '2': Acme Corp
                    required:
                      - phone_number
                  minItems: 1
                  maxItems: 10000
                  description: List of recipients (max 10,000)
                config:
                  type: object
                  properties:
                    call_timeout:
                      type: integer
                      minimum: 15
                      maximum: 120
                      description: Ring timeout in seconds (15-120, default 45)
                    machine_detection_timeout:
                      type: integer
                      minimum: 5
                      maximum: 60
                      description: >-
                        Voicemail detection timeout in seconds (5-60, default
                        30)
                    voicemail_mode:
                      type: string
                      enum:
                        - hangup
                        - tts
                      description: >-
                        Action on voicemail detection: hangup or tts (default:
                        hangup)
                    voicemail_tts_message:
                      type: string
                      maxLength: 500
                      description: >-
                        TTS message for voicemail (used when voicemail_mode is
                        tts)
                    outbound_auto_greet:
                      type: boolean
                      description: >-
                        Agent greets immediately without waiting for recipient
                        (default: true)
                    max_concurrent:
                      type: integer
                      minimum: 1
                      maximum: 10
                      description: Max concurrent calls for this campaign (1-10, default 2)
              required:
                - name
                - project_id
                - scheduled_at
                - recipients
      responses:
        '201':
          description: Campanha criada
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
                description: Id desta requisição na trilha de auditoria (cite-o ao suporte)
              required: true
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  status:
                    type: string
                  channel:
                    type: string
                  template_name:
                    type:
                      - string
                      - 'null'
                  scheduled_at:
                    type: string
                  agent:
                    type:
                      - object
                      - 'null'
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                    required:
                      - id
                      - name
                  phone_number:
                    type:
                      - object
                      - 'null'
                    properties:
                      id:
                        type: string
                      number:
                        type: string
                      friendly_name:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - number
                      - friendly_name
                  config: {}
                  total_recipients:
                    type: number
                  created_at:
                    type: string
                required:
                  - id
                  - name
                  - status
                  - channel
                  - template_name
                  - scheduled_at
                  - agent
                  - phone_number
                  - total_recipients
                  - created_at
        '400':
          description: >-
            Bad Request: campo inválido ou JSON malformado no corpo da
            requisição
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '402':
          description: Saldo insuficiente
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '403':
          description: Limite mensal de ligações do plano atingido (canal voice)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '404':
          description: Projeto ou template não encontrado (canal whatsapp)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '413':
          description: >-
            Corpo da requisição acima do teto de 10 MB (a lista de destinatários
            é grande demais)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '422':
          description: >-
            Template não aprovado/desabilitado ou quota de conversas da Meta
            excedida (canal whatsapp)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '502':
          description: >-
            Falha na comunicação com o serviço de WhatsApp. ATENÇÃO: um 502 aqui
            NÃO garante que a campanha deixou de ser criada: a criação pode ter
            sido concluída do outro lado depois do timeout. Antes de repetir a
            chamada, liste suas campanhas (GET /api/v1/campaigns); repetir às
            cegas duplica o disparo para toda a lista
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '503':
          description: >-
            Canal whatsapp indisponível (integração não configurada) ou, no
            canal voice, o limite do plano não pôde ser verificado. Nada é
            criado; repita depois
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
      security:
        - ApiKey: []
components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key da organização (Authorization: Bearer ik_live_xxx)'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.