Criar campanha

POST /campaigns

Cria uma campanha em um de dois modos (um ou outro, no mesmo corpo):

Simples: a mesma mensagem para vários. Envie recipients (os destinos) e message.
Avançada: uma mensagem para cada destino. Envie messages, cada item com to e message (e status_post, se quiser).

A mensagem tem o formato do corpo do POST /messages, sem to. As mensagens saem com intervalo sorteado entre delay_min_seconds e delay_max_seconds, a partir de scheduled_at (sem ele, agora). Enquanto houver envio direto em andamento, a campanha espera. Os exemplos ao lado mostram os dois modos.

Autenticação

[
  {
    "token": []
  }
]

{
  "token": {
    "name": "token",
    "type": "apiKey",
    "in": "header"
  }
}

Corpo da requisição

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "description": "Simples: `recipients` e `message` (a mesma mensagem para todos). Avançada: `messages` (cada uma com o seu `to`). Um dos dois.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nome da campanha."
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "description": "Quando começa; sem ele, agora. Até 365 dias à frente; com arquivo em base64 (ou a URL de `/files/uploads/` devolvida pela API) em alguma mensagem, até 30 dias. Para mais longe, mande o arquivo por uma URL pública."
          },
          "delay_min_seconds": {
            "type": "integer",
            "minimum": 0,
            "description": "Intervalo mínimo entre uma mensagem e a próxima, em segundos. Sem os dois campos valem `1` e `3` (como o painel; o intervalo de cada mensagem sai entre 1 e 2 s); com um só, o outro vale `0`; com os dois em `0`, sai sem intervalo."
          },
          "delay_max_seconds": {
            "type": "integer",
            "minimum": 0,
            "description": "Intervalo máximo, em segundos. O intervalo de cada mensagem é sorteado de `delay_min_seconds` até um segundo a menos que este valor (o máximo em si não sai). Se não for maior que o mínimo, o sorteio é entre o mínimo e o mínimo + 1 s: não existe intervalo fixo."
          },
          "recipients": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            },
            "description": "Simples: números com DDI ou ids (inclusive grupos). Repetidos e inválidos são ignorados (a diferença entre `recipients` e o `total` da campanha); sem nenhum válido, `400`."
          },
          "message": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CampaignMessage"
              },
              {
                "$ref": "#/components/schemas/CampaignStatusText"
              }
            ],
            "description": "A mensagem, no formato do envio. Com `status_post`, o texto aceita também `background_color` e `font` (como em `POST /status-posts`)."
          },
          "status_post": {
            "type": "boolean",
            "description": "Simples: publica no status de cada grupo de `recipients` (todos precisam ser grupos; só texto, imagem e vídeo)."
          },
          "messages": {
            "type": "array",
            "minItems": 1,
            "description": "Avançada: cada mensagem com o destino. Destino inválido recusa o pedido todo (`400`, com a posição da mensagem em `message`).",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "to",
                "message"
              ],
              "properties": {
                "to": {
                  "type": "string",
                  "description": "Número com DDI ou id."
                },
                "message": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/CampaignMessage"
                    },
                    {
                      "$ref": "#/components/schemas/CampaignStatusText"
                    }
                  ],
                  "description": "A mensagem, no formato do envio. Com `status_post`, o texto aceita também `background_color` e `font` (como em `POST /status-posts`)."
                },
                "status_post": {
                  "type": "boolean",
                  "description": "Publica no status do grupo `to` (só texto, imagem e vídeo)."
                }
              }
            }
          }
        },
        "oneOf": [
          {
            "title": "Simples",
            "required": [
              "recipients",
              "message"
            ],
            "not": {
              "required": [
                "messages"
              ]
            }
          },
          {
            "title": "Avançada",
            "required": [
              "messages"
            ],
            "not": {
              "anyOf": [
                {
                  "required": [
                    "recipients"
                  ]
                },
                {
                  "required": [
                    "message"
                  ]
                },
                {
                  "required": [
                    "status_post"
                  ]
                }
              ]
            }
          }
        ]
      },
      "examples": {
        "simples": {
          "summary": "Simples: a mesma mensagem para vários",
          "value": {
            "name": "Black Friday",
            "scheduled_at": "2026-11-27T12:00:00.000Z",
            "delay_min_seconds": 10,
            "delay_max_seconds": 30,
            "recipients": [
              "5511999999999",
              "5511988888888"
            ],
            "message": {
              "type": "text",
              "text": "Só hoje: 30% em tudo!"
            }
          }
        },
        "avancada": {
          "summary": "Avançada: uma mensagem para cada um",
          "value": {
            "name": "Lembrete de pagamento",
            "delay_min_seconds": 20,
            "delay_max_seconds": 60,
            "messages": [
              {
                "to": "5511999999999",
                "message": {
                  "type": "text",
                  "text": "Oi, Maria! Sua fatura vence amanhã."
                }
              },
              {
                "to": "5511988888888",
                "message": {
                  "type": "document",
                  "url": "https://loja.com/boleto-123.pdf",
                  "filename": "boleto.pdf",
                  "text": "Oi, João! Segue o boleto."
                }
              }
            ]
          }
        },
        "status_grupos": {
          "summary": "Simples no status dos grupos",
          "value": {
            "name": "Aviso nos grupos",
            "recipients": [
              "120363028782550019@g.us"
            ],
            "status_post": true,
            "message": {
              "type": "text",
              "text": "Loja fechada no feriado."
            }
          }
        }
      }
    }
  }
}

Respostas

{
  "201": {
    "description": "Criada.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Campaign"
        },
        "example": {
          "id": "r7f3a9c2e1b4d5f",
          "name": "Black Friday",
          "status": "scheduled",
          "scheduled_at": "2026-11-27T12:00:00.000Z",
          "delay_min_seconds": 10,
          "delay_max_seconds": 30,
          "total": 2,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "played": 0,
          "failed": 0,
          "created_at": "2026-11-26T18:00:00.000Z",
          "updated_at": "2026-11-27T12:40:00.000Z"
        }
      }
    }
  },
  "400": {
    "description": "Pedido inválido.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "invalid_request",
          "message": "Envie recipients e message, ou messages."
        }
      }
    }
  },
  "401": {
    "description": "Token inválido ou ausente.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "unauthorized",
          "message": "Token inválido."
        }
      }
    }
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/InternalError"
  },
  "501": {
    "description": "O canal da inbox não tem o tipo de uma das mensagens (`unsupported_for_channel`). O `message` diz qual.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "unsupported_for_channel",
          "message": "poll não está disponível neste canal."
        }
      }
    }
  },
  "503": {
    "$ref": "#/components/responses/Disconnected"
  }
}

Estado: Disponível

Compatibilidade de canais

Canal	Compatível	Observação
WhatsApp (Web)	Sim
WhatsApp (API oficial)	Não	Campanhas ainda só no WhatsApp Web.
Instagram	Não
Messenger	Não
Telegram	Não

Eventos que esta rota gera

O que chega no seu webhook (ou em GET /events) depois desta rota.

`campaign.updated`: início e fim

{
  "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H",
  "type": "campaign.updated",
  "created_at": "2026-10-17T12:00:00.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_web"
  },
  "data": {
    "id": "r7f3a9c2e1b4d5f",
    "status": "sending",
    "total": 500,
    "name": "Promoção de outubro",
    "sent": 0,
    "failed": 0,
    "updated_at": "2026-10-17T12:00:00.000Z"
  }
}

`message.status`: cada mensagem

{
  "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H",
  "type": "message.status",
  "created_at": "2026-10-17T12:00:00.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_web"
  },
  "data": {
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "lid": "123456789012345@lid",
      "type": "direct"
    },
    "status": "delivered",
    "at": "2026-10-17T12:00:00.000Z",
    "messages": [
      {
        "id": "3EB05DCE1D4036FCE241C6"
      },
      {
        "id": "3EB0A7F2C91D"
      }
    ]
  }
}

`message.failed`: cada mensagem da campanha que falhar

{
  "id": "evt_01JAB3M7Q2W8R4T6V9X0YZ1K2C",
  "type": "message.failed",
  "created_at": "2026-10-17T12:00:00.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_web"
  },
  "data": {
    "message": {
      "id": "3EB05DCE1D4036FCE241C6",
      "chat_id": "5511999999999@s.whatsapp.net",
      "author": {
        "id": "5511888888888@s.whatsapp.net",
        "name": "Loja"
      },
      "direction": "out",
      "sent_by": "api",
      "sent_at": "2026-10-17T12:00:00.000Z",
      "category": "unsent",
      "type": "text",
      "text": "Seu pedido saiu para entrega.",
      "status": "failed",
      "error": {
        "error": "send_failed",
        "message": "O número não tem WhatsApp."
      },
      "campaign_id": "r7f3a9c2e1b4d5f"
    },
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "lid": "123456789012345@lid",
      "type": "direct"
    }
  }
}

Antes e depois (uazapi → Orkesio)

Na uazapi: POST /sender/simple, POST /sender/advanced.

Uma rota para simples e avançada; cada mensagem no formato do corpo do POST /messages (sem to).
numbers → recipients; folder → name; delayMin/delayMax → delay_min_seconds/delay_max_seconds; scheduled_for (ms, segundos ou minutos a partir de agora) → scheduled_at (data ISO); groupStatus → status_post.
Responde a campanha (antes folder_id, count e status).

#/components/schemas/CampaignMessage

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "text",
        "image",
        "video",
        "video_note",
        "audio",
        "voice",
        "document",
        "sticker",
        "location",
        "contacts",
        "poll",
        "buttons",
        "list",
        "carousel",
        "location_request",
        "payment",
        "event"
      ],
      "description": "Tipo da mensagem. Os campos dele vão soltos, ao lado de `type`, no formato do envio."
    },
    "mentions": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Número ou id do participante."
      },
      "description": "Quem mencionar (grupos). Todo `@número` escrito no `text` (texto, legenda de mídia, enquete, botões, lista e carrossel) já vira menção, e `@todos` ou `@all` menciona todos. Em grupo que usa LID, a menção e o `@número` do texto saem com o LID do participante, como o WhatsApp faz. Evento, localização e contato não leem o texto."
    },
    "mention_all": {
      "type": "boolean",
      "description": "Menciona todos do grupo, sem aparecer no texto."
    },
    "forwarded": {
      "type": "boolean",
      "description": "Mostra como encaminhada."
    }
  },
  "required": [
    "type"
  ],
  "description": "Mensagem da campanha, no formato do [envio](/docs/enviar) (`type` e os campos do tipo, e `mentions`, `mention_all`, `forwarded`), sem `to`: o destino é cada destinatário. Vale qualquer tipo do envio menos `template` (400). Arquivo em `base64` ou `url`, como no envio.",
  "oneOf": [
    {
      "properties": {
        "type": {
          "const": "text"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentText"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "image"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentImage"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "video"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentVideo"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "video_note"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentVideoNote"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "audio"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentAudio"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "voice"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentVoice"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "document"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentDocument"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "sticker"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentSticker"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "location"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentLocation"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "contacts"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentContacts"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "poll"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentPoll"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "buttons"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentButtons"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "list"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentList"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "carousel"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentCarousel"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "location_request"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentLocationRequest"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "payment"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentPayment"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "event"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentEvent"
        }
      ]
    }
  ],
  "unevaluatedProperties": false
}

#/components/schemas/SendContentText

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "O texto da mensagem (com a formatação do WhatsApp). Vai como está: um `>1` respondendo a uma enquete é texto (o voto é `type: poll_vote`; a resposta a botões, `interactive_reply`)."
    },
    "link_preview": {
      "oneOf": [
        {
          "type": "boolean",
          "description": "`true`: prévia automática do primeiro link (o mesmo que omitir). `false`: sem prévia."
        },
        {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Título da prévia."
            },
            "description": {
              "type": "string",
              "description": "Texto de descrição da prévia."
            },
            "image_url": {
              "type": "string",
              "description": "Link da imagem da prévia."
            },
            "large": {
              "type": "boolean",
              "description": "Mostra a imagem grande, em vez da miniatura."
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "Prévia do link. Sem o campo, a api monta a prévia do primeiro link do texto; `false` desliga; um objeto define os dados da prévia."
    }
  },
  "required": [
    "text"
  ],
  "title": "texto"
}

#/components/schemas/SendContentImage

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    }
  },
  "title": "imagem"
}

#/components/schemas/SendContentVideo

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    },
    "animated": {
      "type": "boolean",
      "description": "Envia como GIF: o vídeo toca em loop e sem som, como os GIFs do WhatsApp (mande um MP4). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`. Só vale em `type: video`."
    }
  },
  "title": "vídeo"
}

#/components/schemas/SendContentVideoNote

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    }
  },
  "title": "vídeo redondo"
}

#/components/schemas/SendContentAudio

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    }
  },
  "title": "áudio"
}

#/components/schemas/SendContentVoice

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    }
  },
  "title": "voz"
}

#/components/schemas/SendContentDocument

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    }
  },
  "title": "documento"
}

#/components/schemas/SendContentSticker

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    }
  },
  "title": "figurinha"
}

#/components/schemas/SendContentLocation

{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "description": "Latitude."
    },
    "longitude": {
      "type": "number",
      "description": "Longitude."
    },
    "name": {
      "type": "string",
      "description": "O nome do lugar."
    },
    "address": {
      "type": "string",
      "description": "Endereço."
    }
  },
  "required": [
    "latitude",
    "longitude"
  ],
  "title": "localização"
}

#/components/schemas/SendContentContacts

{
  "type": "object",
  "required": [
    "contacts"
  ],
  "properties": {
    "contacts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nome exibido."
          },
          "phones": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "Número com DDI."
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "number"
                  ],
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "Número com DDI."
                    },
                    "wa_id": {
                      "type": "string",
                      "description": "Ignorado no envio (vem na mensagem recebida)."
                    }
                  }
                }
              ]
            },
            "description": "Telefones: o número com DDI, ou o objeto da mensagem recebida (`{\"number\": \"...\"}`), para reenviar como veio."
          },
          "email": {
            "type": "string",
            "description": "E-mail."
          },
          "organization": {
            "type": "string",
            "description": "Empresa."
          },
          "url": {
            "type": "string",
            "description": "Site."
          }
        },
        "required": [
          "name",
          "phones"
        ],
        "additionalProperties": false
      },
      "description": "Contato a compartilhar. Por enquanto vai um por mensagem: a lista precisa ter exatamente um item (com mais, responde 400).",
      "minItems": 1,
      "maxItems": 1
    }
  },
  "title": "contatos"
}

#/components/schemas/SendContentPoll

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "A pergunta."
    },
    "choices": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Opção."
      },
      "description": "Opções."
    },
    "selectable_count": {
      "type": "integer",
      "description": "Quantas opções o contato pode escolher: de `0` (várias) até o número de opções."
    }
  },
  "required": [
    "text",
    "choices"
  ],
  "title": "enquete"
}

#/components/schemas/SendContentButtons

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "O texto, acima das opções. Quando há texto depois da primeira linha, ela é o cabeçalho (em negrito) e o resto é o corpo. Com uma linha só, ela vai como cabeçalho, sem corpo, também junto da mídia do cabeçalho. Na API oficial, o texto vai inteiro no corpo."
    },
    "footer": {
      "type": "string",
      "description": "Rodapé."
    },
    "url": {
      "type": "string",
      "description": "Mídia do cabeçalho (imagem, vídeo ou documento): link público do arquivo. Use `url` ou `base64`. O tipo sai do arquivo; na API oficial, da extensão do link (imagem quando não há)."
    },
    "base64": {
      "type": "string",
      "description": "Mídia do cabeçalho em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo do cabeçalho. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo do cabeçalho (documentos)."
    },
    "button_text": {
      "type": "string",
      "description": "Texto do botão que abre a lista (só `list`)."
    },
    "choices": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/OrkesioOption"
      },
      "description": "Botões (`buttons`) ou itens (`list`, agrupados por `section`). Sem `id`, a api usa o `title`. `title`, `id` e `value` não aceitam `|` nem quebra de linha; em `list`, `section` e `description` também não aceitam `[` e `]`. Na API oficial, `call` e `copy` respondem `unsupported_for_channel`."
    },
    "legacy": {
      "type": "boolean",
      "description": "Só `buttons`, só WhatsApp Web: envia no formato antigo de botões (`ButtonsMessage`), para quem ainda usa. Só botões de resposta (sem `url`, `call` e `copy`) e sem mídia no cabeçalho; o `text` vai inteiro no corpo, sem cabeçalho. O WhatsApp pode deixar de mostrar esse formato a qualquer momento. Nos outros canais responde `unsupported_for_channel`."
    }
  },
  "required": [],
  "title": "botões"
}

#/components/schemas/OrkesioOption

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id."
    },
    "title": {
      "type": "string",
      "description": "Título."
    },
    "description": {
      "type": "string",
      "description": "Descrição."
    },
    "action": {
      "type": "string",
      "enum": [
        "reply",
        "url",
        "call",
        "copy"
      ],
      "description": "O que o botão faz."
    },
    "value": {
      "type": "string",
      "description": "Link, telefone ou código, conforme `action`."
    },
    "section": {
      "type": "string",
      "description": "Seção (listas)."
    }
  },
  "required": [
    "title"
  ],
  "additionalProperties": false,
  "description": "Opção de menu ou botão."
}

#/components/schemas/SendContentList

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "O texto, acima das opções. Quando há texto depois da primeira linha, ela é o cabeçalho (em negrito) e o resto é o corpo. Com uma linha só, ela vai como cabeçalho, sem corpo. Na API oficial, o texto vai inteiro no corpo. A lista não aceita mídia no cabeçalho."
    },
    "footer": {
      "type": "string",
      "description": "Rodapé."
    },
    "button_text": {
      "type": "string",
      "description": "Texto do botão que abre a lista (só `list`)."
    },
    "choices": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/OrkesioOption"
      },
      "description": "Botões (`buttons`) ou itens (`list`, agrupados por `section`). Sem `id`, a api usa o `title`. `title`, `id` e `value` não aceitam `|` nem quebra de linha; em `list`, `section` e `description` também não aceitam `[` e `]`. Na API oficial, `call` e `copy` respondem `unsupported_for_channel`."
    }
  },
  "required": [],
  "title": "lista"
}

#/components/schemas/SendContentCarousel

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "O corpo: o texto principal, acima das opções."
    },
    "footer": {
      "type": "string",
      "description": "Rodapé."
    },
    "choices": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/OrkesioOption"
      },
      "description": "Botões (`buttons`) ou itens (`list`, agrupados por `section`). Sem `id`, a api usa o `title`. `title`, `id` e `value` não aceitam `|` nem quebra de linha; em `list`, `section` e `description` também não aceitam `[` e `]`. Na API oficial, `call` e `copy` respondem `unsupported_for_channel`."
    },
    "cards": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "image",
              "video",
              "document"
            ],
            "description": "O tipo da mídia do cartão."
          },
          "url": {
            "type": "string",
            "description": "Link público do arquivo. Use `url` ou `base64`."
          },
          "base64": {
            "type": "string",
            "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
          },
          "mime_type": {
            "type": "string",
            "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
          },
          "filename": {
            "type": "string",
            "description": "Nome do arquivo (documentos)."
          },
          "thumbnail": {
            "type": "string",
            "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
          },
          "view_once": {
            "type": "boolean",
            "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
          },
          "text": {
            "type": "string",
            "description": "Texto."
          },
          "choices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrkesioOption"
            },
            "description": "Botões do card. `title`, `id` e `value` não aceitam aspas, `\\` nem quebra de linha."
          }
        },
        "additionalProperties": false
      },
      "description": "Cards (`carousel`): a mídia (`type` e `url` ou `base64`), o `text` e os `choices` de cada cartão."
    }
  },
  "required": [],
  "title": "carrossel"
}

#/components/schemas/SendContentLocationRequest

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "O pedido, acima do botão \"Enviar localização\"."
    }
  },
  "required": [
    "text"
  ],
  "title": "pedido de localização"
}

#/components/schemas/SendContentPayment

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "description": "Valor. Sem `amount` e só com `pix`, sai o botão de copiar a chave; nesse caso `title`, `note`, `footer`, `currency` e `reference_id` respondem 400."
    },
    "currency": {
      "type": "string",
      "description": "Moeda (padrão `BRL`)."
    },
    "reference_id": {
      "type": "string",
      "description": "Número do pedido ou da fatura."
    },
    "order_id": {
      "type": "string",
      "description": "Mensagem de pedido (`order`) recebida do contato que esta cobrança atende: o `id` dela."
    },
    "title": {
      "type": "string",
      "description": "Título."
    },
    "text": {
      "type": "string",
      "description": "A nota da cobrança."
    },
    "footer": {
      "type": "string",
      "description": "Rodapé."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Item."
          },
          "quantity": {
            "type": "number",
            "description": "Quantidade, inteiro a partir de 1."
          },
          "amount": {
            "type": "number",
            "description": "Valor do item. Ainda não é aceito (400): use `payment.amount`."
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "description": "Itens da cobrança. Por enquanto, um item por cobrança.",
      "maxItems": 1
    },
    "pix": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Chave PIX."
        },
        "key_type": {
          "type": "string",
          "enum": [
            "cpf",
            "cnpj",
            "phone",
            "email",
            "evp"
          ],
          "description": "Tipo da chave (padrão `evp`)."
        },
        "merchant_name": {
          "type": "string",
          "description": "Recebedor."
        }
      },
      "required": [
        "key"
      ],
      "additionalProperties": false
    },
    "boleto": {
      "type": "string",
      "description": "Linha digitável do boleto."
    },
    "link": {
      "type": "string",
      "description": "Link de pagamento (só domínios homologados pelo WhatsApp)."
    },
    "invoice": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "Link público do arquivo. Use `url` ou `base64`."
        },
        "base64": {
          "type": "string",
          "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
        },
        "mime_type": {
          "type": "string",
          "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
        },
        "filename": {
          "type": "string",
          "description": "Nome do arquivo (documentos)."
        },
        "thumbnail": {
          "type": "string",
          "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
        },
        "view_once": {
          "type": "boolean",
          "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
        }
      },
      "additionalProperties": false,
      "description": "Fatura (PDF): o arquivo, sem legenda."
    }
  },
  "title": "cobrança"
}

#/components/schemas/SendContentEvent

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "O nome do evento."
    },
    "description": {
      "type": "string",
      "description": "Descrição."
    },
    "start_at": {
      "type": "string",
      "format": "date-time",
      "description": "Início. ISO 8601 em UTC com milissegundos."
    },
    "end_at": {
      "type": "string",
      "format": "date-time",
      "description": "Fim. ISO 8601 em UTC com milissegundos."
    },
    "location": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Nome do local."
        },
        "address": {
          "type": "string",
          "description": "Endereço."
        },
        "latitude": {
          "type": "number",
          "description": "Latitude."
        },
        "longitude": {
          "type": "number",
          "description": "Longitude."
        }
      },
      "additionalProperties": false
    },
    "join_link": {
      "type": "string",
      "description": "Link da chamada (HTTPS). Com ele, o evento vira chamada agendada."
    },
    "extra_guests_allowed": {
      "type": "boolean",
      "description": "Convidado pode levar acompanhante."
    },
    "reminder_minutes": {
      "type": "integer",
      "description": "Lembrete, em minutos antes do início."
    },
    "canceled": {
      "type": "boolean",
      "description": "Evento cancelado."
    }
  },
  "required": [
    "text",
    "start_at"
  ],
  "title": "evento"
}

#/components/schemas/CampaignStatusText

{
  "type": "object",
  "required": [
    "type",
    "text"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "text"
    }
  },
  "description": "Status de texto com cor e fonte (só com `status_post`), como em `POST /status-posts`.",
  "allOf": [
    {
      "$ref": "#/components/schemas/StatusContentText"
    }
  ],
  "unevaluatedProperties": false
}

#/components/schemas/StatusContentText

{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "description": "O texto da mensagem (com a formatação do WhatsApp)."
    },
    "background_color": {
      "type": "integer",
      "minimum": 1,
      "maximum": 19,
      "description": "Cor de fundo, de 1 a 19 (as cores do WhatsApp); padrão 19, cinza escuro."
    },
    "font": {
      "type": "integer",
      "enum": [
        0,
        1,
        2,
        6,
        7,
        8,
        9,
        10
      ],
      "description": "Fonte do texto (os números de fonte do WhatsApp); padrão `0`."
    }
  },
  "title": "texto"
}

#/components/schemas/Campaign

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status"
  ],
  "description": "Campanha (envio em massa). Cada mensagem conta em um só entre `delivered`, `read` e `played`; `sent` é o total que saiu, e já inclui esses três. Entregues no total = `delivered` + `read` + `played`.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id da campanha (o `campaign_id` das mensagens)."
    },
    "name": {
      "type": "string",
      "description": "Nome da campanha."
    },
    "status": {
      "type": "string",
      "enum": [
        "scheduled",
        "sending",
        "paused",
        "done"
      ],
      "description": "`scheduled` (esperando a hora), `sending`, `paused` ou `done`. A campanha também se pausa sozinha quando o WhatsApp restringe a conta de iniciar conversas (`account_restricted` ou `new_chat_limit`): a mensagem recusada volta a agendada, sai o `campaign.updated` e o motivo (com até quando) está em `GET /inbox/limits`. Retomar é com `PATCH /campaigns` (`status: scheduled`); enquanto a restrição durar, ela se pausa de novo."
    },
    "scheduled_at": {
      "type": "string",
      "format": "date-time",
      "description": "Quando começa. ISO 8601 em UTC com milissegundos."
    },
    "delay_min_seconds": {
      "type": "integer",
      "description": "Intervalo mínimo entre mensagens, em segundos."
    },
    "delay_max_seconds": {
      "type": "integer",
      "description": "Intervalo máximo entre mensagens, em segundos."
    },
    "total": {
      "type": "integer",
      "description": "Mensagens na campanha."
    },
    "sent": {
      "type": "integer",
      "description": "Saíram com sucesso (`delivered`, `read` e `played` já estão aqui dentro)."
    },
    "delivered": {
      "type": "integer",
      "description": "Entregues e ainda não lidas."
    },
    "read": {
      "type": "integer",
      "description": "Lidas (as ouvidas ou vistas contam em `played`)."
    },
    "played": {
      "type": "integer",
      "description": "Ouvidas ou vistas (áudio e vídeo)."
    },
    "failed": {
      "type": "integer",
      "description": "Falharam."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Criação. ISO 8601 em UTC com milissegundos."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Última alteração. ISO 8601 em UTC com milissegundos."
    }
  }
}

#/components/schemas/OrkesioError

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Código estável do erro, em inglês e `snake_case`. Os de uso geral: `invalid_request` (400): pedido inválido: JSON malformado, campo desconhecido ou valor fora do permitido (o detalhe em `message`; o campo em `field`, quando é um só); `unauthorized` (401): `token` ou `admintoken` ausente ou inválido; `forbidden` (403): o token não pode fazer isso (no servidor de demonstração, por exemplo); `not_admin` (403): o WhatsApp recusou por falta de permissão no grupo ou na newsletter; `account_restricted` (403): o WhatsApp restringiu a conta de iniciar conversas novas (mandar para quem já conversa continua valendo; até quando, em `GET /inbox/limits`); `new_chat_limit` (403): a conta atingiu a cota do WhatsApp de conversas novas neste ciclo (veja `GET /inbox/limits`); os dois também no `error` de `OrkesioMessage` e de `message.status`, e não adianta repetir o envio; `payment_required` (403): na API oficial, a Meta recusou o envio por um problema no pagamento da conta do WhatsApp Business (erro 131042 da Meta); acerte a forma de pagamento no gerenciador da Meta, porque repetir não adianta; também no `error` de `OrkesioMessage` e de `message.status`; `whatsapp_rejected` (400): o WhatsApp recusou a mudança pedida (o campo, em `field`, quando é um só); `not_found` (404): o recurso não existe nesta inbox; `conflict` (409): o recurso já existe ou mudou (id em uso, inbox de outro canal); `inbox_not_paired` (409): a inbox ainda não conectou um número; `payload_too_large` (413): o corpo passou do limite; `canceled` e `expired`: só no `error` de `OrkesioMessage` e de `message.status` (envio cancelado antes de sair, ou que passou do prazo na fila); `rate_limited` (429): muitos pedidos; espere o `Retry-After`; `internal_error` (500): falha inesperada na api; tente de novo; `send_failed` (500): o envio falhou (o motivo em `message`); também no `error` de `OrkesioMessage` e de `message.status`; `unsupported_for_channel` (501): o canal da inbox não atende esta rota ou este tipo de mensagem; `meta_error` (502): a Meta recusou ou não respondeu; `disconnected` (503): a inbox está desconectada (sem sessão do WhatsApp, ou token do canal oficial vencido); `unavailable` (503 ou 504): o WhatsApp não respondeu a tempo, ou algo em andamento impede agora; tente de novo. Cada rota lista os códigos próprios dela (`outside_window`, `number_invalid`, `flow_invalid`...). A lista pode crescer: trate código desconhecido pelo status HTTP."
    },
    "message": {
      "type": "string",
      "description": "Descrição para pessoas (às vezes o texto do WhatsApp ou da Meta). Não compare o texto: use `error`."
    },
    "field": {
      "type": "string",
      "description": "O campo do pedido que causou o erro, quando é um só (por exemplo, o campo que o WhatsApp recusou num `PATCH`)."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": true,
  "description": "O objeto de erro da Orkesio, o mesmo em todo lugar: o corpo das respostas de erro e o `error` de `OrkesioMessage`, `message.status` e `message.failed`. Algumas rotas juntam campos próprios (`request_id`, `errors`...)."
}

#/components/responses/RateLimited

{
  "description": "`rate_limited`: passou do limite de chamadas desta inbox (ou do admin); espere o tempo do header `Retry-After` e tente de novo.",
  "headers": {
    "Retry-After": {
      "description": "Segundos até poder chamar de novo.",
      "schema": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "rate_limited",
        "message": "Muitas requisições."
      }
    }
  }
}

#/components/responses/InternalError

{
  "description": "`internal_error`: falha inesperada na api (no banco, por exemplo); tente de novo.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "internal_error",
        "message": "Falha inesperada."
      }
    }
  }
}

#/components/responses/Disconnected

{
  "description": "`disconnected`: a inbox está desconectada do WhatsApp (a api esperou a sessão e tentou reconectar). `unavailable`: o WhatsApp não respondeu agora; tente de novo.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "disconnected",
        "message": "Instância desconectada do WhatsApp."
      }
    }
  }
}

Guias relacionados

Visão geral · O que funciona em cada canal · O que muda da uazapi