API - Documentação

Arquitetura Positus - WhatsApp Business API

Você pode integrar diretamente com a Positus API (acima) ou usar uma plataforma de atendimento como o Invenio da Robbu, sem desenvolver a integração.

SDK
https://github.com/positusapps/positus-api-laravel-client	Laravel / PHP	Youtube
https://github.com/positusapps/positus-api-php-client	PHP	Youtube
https://www.nuget.org/packages/positus-api-csharp-client/	Nuget .NET / .NET Core	YouTube
https://github.com/positusapps/positus-api-csharp-client	Github para .NET

Token de Produção: O seu token será gerado e fornecido pela Positus, ele dará acesso a todos os seus números de WhatsApp Business API. A chave será fornecido após ativação de cada número de WhatsApp Business API.Sandbox - Token desenvolvimento: Você poderá gerar o seu token diretamente pelo http://studio.posit.us/.

Postman file

O Postman é uma ferramenta que tem como objetivo testar serviços RESTful (Web APIs) por meio do envio de requisições HTTP e da análise do seu retorno. Download Postman App

API de produção

Positus API (2026).postman_collection.json

API de desenvolvimento (Sandbox)

Positus API Sandbox (2026).postman_collection.json

messages

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Utilize esta rota para enviar mensagens de texto via WhatsApp

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Content-Type	string	application/json
Authorization	string	Autenticação usando Bearer Token

Request Body

{
  "to": "+5511999999999",
  "type": "text",
  "text": {
    "body": "your-message-content"
  }
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

{
    "errors": [
        {
            "code": ,
            "title": "",
            "details": ""
        }
    ],
    "message": ""
}

Destinatário: telefone (`to`) ou BSUID (`recipient`)

Todas as rotas de envio de mensagem aceitam duas formas de identificar o destinatário. Use uma OU outra:

Campo	Tipo	Obrigatoriedade	Descrição
`to`	string	Obrigatório se `recipient` for omitido	Telefone do destinatário no formato internacional (ex.: `+5511999999999`).
`recipient`	string	Opcional — envie no lugar de `to`	BSUID (Business-Scoped User ID) ou parent BSUID do destinatário (ex.: `BR.1234567890`). Veja BSUID e identificadores de usuário.

O BSUID é um identificador de usuário escopado ao portfólio de negócios, entregue no campo user_id dos webhooks. Ele é útil quando o usuário adotou um username e o telefone (wa_id) pode não vir no payload. Entenda o conceito em BSUID e identificadores de usuário.

Precedência quando to e recipient coexistem: se você enviar os dois campos na mesma requisição, o telefone (to) prevalece — a mensagem é entregue ao telefone. Por isso, envie apenas um dos dois: só to (telefone) ou só recipient (BSUID/parent BSUID).

Números on-premises aceitam somente to (telefone). O envio por recipient (BSUID) está disponível apenas para números na Cloud API (Meta).

Request Body (envio para BSUID)

{
  "recipient": "BR.1234567890",
  "type": "text",
  "text": {
    "body": "your-message-content"
  }
}

Response (envio para BSUID)

A resposta é a mesma dos demais envios, mas o bloco contacts — repassado da Meta — traz o identificador que você usou em input, além do telefone (wa_id, quando disponível) e do BSUID (user_id).

{
    "contacts": [
        {
            "input": "BR.1234567890",
            "wa_id": "5511999999999",
            "user_id": "BR.1234567890"
        }
    ],
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

{
    "errors": [
        {
            "code": 131062,
            "title": "Business-scoped User ID (BSUID) recipients are not supported for this message.",
            "details": "Business-scoped User ID (BSUID) recipients are not supported for this message."
        }
    ]
}

Casos especiais que exigem telefone (não aceitam BSUID): templates de autenticação dos tipos one-tap, zero-tap e copy-code. Nesses casos, informe sempre to (telefone). Se você enviar um BSUID onde ele não é suportado, a Meta responde com o erro 131062.

Indicador de digitação

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages/typing-indicator Exibe o indicador “digitando…” para o cliente e marca como lida a mensagem recebida. Informe o message_id da mensagem enviada pelo cliente. O indicador é dispensado automaticamente após cerca de 25 segundos ou assim que você responde.

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

Name	Type	Description
message_id	string	Obrigatório. ID da mensagem recebida do cliente.

{
  "message_id": "wamid.HBgMNTUxMTk5OTk5OTk5FMA=="
}

Response

200
Erro

{
    "success": true,
    "message": "The typing indicator was sent successfully"
}

{
    "errors": [
        {
            "code": 0,
            "title": "",
            "details": ""
        }
    ],
    "message": "Unfortunately, we were unable to send the typing indicator"
}

HSM

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Utilize esta rota para enviar mensagens de notificação via WhatsApp HSM - São templates de mensagens pré-aprovadas pelo Facebook, podem mensagens de texto, midia ou arquivos.

O destinatário pode ser informado por telefone (to) ou por BSUID (recipient), como descrito em Destinatário: telefone (to) ou BSUID (recipient). Exceção: templates de autenticação one-tap, zero-tap e copy-code exigem o telefone (to) e não aceitam BSUID.

Path Parameters

Name	Type	Description
Chave	string

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

{
  "to": "+551199999999",
  "type": "template",
  "template": {
    "language": {
      "policy": "deterministic",
      "code": "pt_BR"
    },
    "name": "xxxxxx",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://dealers.rewebmkt.com/images/20190417084518-actros-3-1280.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Rafael" },
          { "type": "text", "text": "Mercedes-Benz" },
          { "type": "text", "text": "Actros" },
          { "type": "text", "text": "Cardiesel - Belo Horizonte" },
          { "type": "text", "text": "08/05/2020" }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          { "type": "text", "text": "fMYMyV8x" }
        ]
      }
    ]
  }
}

{
  "to": "+5511999999999",
  "type": "template",
  "template": {
    "language": {
      "policy": "deterministic",
      "code": "pt_BR"
    },
    "name": "carteiro_botoes",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Robbu" },
          { "type": "text", "text": "Thiago Thamiel" }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0"
      }
    ]
  }
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

{
    "errors": [
        {
            "code": ,
            "title": "",
            "details": ""
        }
    ],
    "message": ""
}

Contact

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Compartilhe contatos

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

{
  "to": "+5511999999999",
  "type": "contacts",
  "contacts": [
    {
      "addresses": [],
      "emails": [],
      "ims": [],
      "name": {
        "first_name": "Positus Provider",
        "formatted_name": "Positus Provider"
      },
      "org": [],
      "phones": [
        {
          "phone": "+55 11 2626-4234",
          "type": "CELL",
          "wa_id": "551126264234"
        }
      ],
      "urls": []
    }
  ]
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

{
    "errors": [
        {
            "code": ,
            "title": "",
            "details": ""
        }
    ],
    "message": ""
}

Location

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Compartilhe localizações

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

{
  "to": "+5511999999999",
  "type": "location",
  "location": {
    "longitude": -46.662787,
    "latitude": -23.553610,
    "name": "Robbu Brazil",
    "address": "Av. Angélica, 2530 - Bela Vista, São Paulo - SP, 01228-200"
  }
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

{
    "errors": [
        {
            "code": ,
            "title": "",
            "details": ""
        }
    ],
    "message": ""
}

Image

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Compartilhe imagens

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

{
  "to": "+5511999999999",
  "type": "image",
  "image": {
    "link": "https://picsum.photos/200",
    "caption": "your-document-caption"
  }
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

{
    "errors": [
        {
            "code": ,
            "title": "",
            "details": ""
        }
    ],
    "message": ""
}

Document

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Compartilhe documentos

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

{
  "to": "+5511941489395",
  "type": "document",
  "document": {
    "link": "http://www.pdf995.com/samples/pdf.pdf",
    "caption": "your-document-caption"
  }
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

{
    "errors": [
        {
            "code": ,
            "title": "",
            "details": ""
        }
    ],
    "message": ""
}

Video

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Compartilhe videos

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

{
  "to": "+5511999999999",
  "type": "video",
  "video": {
    "link": "https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4",
    "caption": "your-document-caption"
  }
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

{
    "errors": [
        {
            "code": ,
            "title": "",
            "details": ""
        }
    ],
    "message": ""
}

Audio

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Compartilhe audios

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

{
  "to": "+5511999999999",
  "type": "audio",
  "audio": {
    "link": "https://sample-videos.com/audio/mp3/crowd-cheering.mp3"
  }
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

{
    "errors": [
        {
            "code": ,
            "title": "",
            "details": ""
        }
    ],
    "message": ""
}

Sticker

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Compartilhe adesivos. O Formato do adesivo tem que ser exatamente 512x512

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

{
  "to": "+5511999999999",
  "type": "sticker",
  "sticker": {
    "link": "https://studio.posit.us/api/samples/sticker.webp"
  }
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

Download Midia

GET https://api.positus.global/v2/whatsapp/numbers/{{chave}}/media/{{messages.type.id}} Faça o download das mídias. Use o id da mídia recebido na notificação de webhook.

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp
id	string	ID da mídia (recebido no webhook)

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token

Response

Retorna o conteúdo binário da mídia, com o cabeçalho Content-Type correspondente ao tipo do arquivo (ex.: image/jpeg, audio/ogg, application/pdf).

Limite de requisições atingido na Meta. A resposta inclui o cabeçalho Retry-After (em segundos) indicando quando tentar novamente.

{
    "message": "..."
}

Mensagens Interativas - Lista

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Listar Mensagens: Mensagens incluindo um menu de até 10 opções. Esse tipo de mensagem oferece uma maneira mais simples e consistente para os usuários fazerem uma seleção ao interagir com uma empresa. Mensagens de botão de lista ou de resposta não podem ser usadas como notificações. Atualmente, eles só podem ser enviados dentro de 24 horas da última mensagem enviada pelo usuário. Se você tentar enviar uma mensagem fora da janela de 24 horas, você receberá uma mensagem de erro.

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

{
  "to": "+5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "CryptoBank"
    },
    "body": {
      "text": "Olá senhor Thiago Thamiel, me chamo Francisco Dabus estou falando referente ao Banco CryptoBank e você já pode regular sua pendência financeira por aqui. Veja as opções que preparamos para você!\n\n💼 Contrato: 82782361236213\n🗓️ Vencimento: 01/01/2021\n💰 Valor Atualizado: 232,83"
    },
    "footer": {
      "text": "Demonstração Robbu"
    },
    "action": {
      "button": "Opções de pagamento",
      "sections": [
        {
          "title": "Atualização",
          "rows": [
            {
              "id": "7",
              "title": "Vencimento Hoje",
              "description": "💰 R$ 201,23 - Parcelas 17 até 19 de 24"
            },
            {
              "id": "1",
              "title": "Vencimento Amanha",
              "description": "💰 R$ 219,32 - Parcelas 17 até 19 de 24"
            }
          ]
        },
        {
          "title": "Quitação",
          "rows": [
            {
              "id": "3",
              "title": "Vencimento Hoje",
              "description": "💰 R$ 1.323,21 - Todas as parcelas restantes"
            },
            {
              "id": "4",
              "title": "Vencimento Amanha",
              "description": "💰 R$ 1.382,34 - Todas as parcelas restantes"
            }
          ]
        }
      ]
    }
  }
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

Documentação completa: https://developers.facebook.com/docs/whatsapp/guides/interactive-messages

Mensagens Interativas - Botões

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Botões de resposta: Mensagens incluindo até 3 opções — cada opção é um botão. Esse tipo de mensagem oferece uma maneira mais rápida para os usuários fazerem uma seleção a partir de um menu ao interagir com uma empresa. Os botões de resposta têm a mesma experiência do usuário que modelos interativos com botões. Mensagens de botão de lista ou de resposta não podem ser usadas como notificações. Atualmente, eles só podem ser enviados dentro de 24 horas da última mensagem enviada pelo usuário. Se você tentar enviar uma mensagem fora da janela de 24 horas, você receberá uma mensagem de erro.

Path Parameters

Name	Type	Description
Chave	string	Código único por número de WhatsApp

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

{
  "to": "+5511999999999",
  "type": "interactive",
  "recipient_type": "individual",
  "interactive": {
    "type": "button",
    "header": {
      "type": "text",
      "text": "1 mês grátis"
    },
    "body": {
      "text": "Ótima escolha, agora você já pode ativar o seu número e realizar testes por 1 mês sem compromisso."
    },
    "footer": {
      "text": "https://posit.us"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id-1",
            "title": "Criar conta grátis"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id-2",
            "title": "Falar com atendente"
          }
        }
      ]
    }
  }
}

Response

{
    "messages": [
        {
            "id": "gBGHVRGZmZmZnwIJpWDiExk7olMZ"
        }
    ],
    "message": "The message was successfully sent"
}

Documentação completa: https://developers.facebook.com/docs/whatsapp/guides/interactive-messages

​Arquitetura Positus - WhatsApp Business API

​Postman file

API de produção

API de desenvolvimento (Sandbox)

​messages

​Path Parameters

​Headers

​Request Body

​Response

​Destinatário: telefone (to) ou BSUID (recipient)

​Request Body (envio para BSUID)

​Response (envio para BSUID)

​Indicador de digitação

​Path Parameters

​Headers

​Request Body

​Response

​HSM

​Path Parameters

​Headers

​Request Body

​Response

​Contact

​Path Parameters

​Headers

​Request Body

​Response

​Location

​Path Parameters

​Headers

​Request Body

​Response

​Image

​Path Parameters

​Headers

​Request Body

​Response

​Document

​Path Parameters

​Headers

​Request Body

​Response

​Video

​Path Parameters

​Headers

​Request Body

​Response

​Audio

​Path Parameters

​Headers

​Request Body

​Response

​Sticker

​Path Parameters

​Headers

​Request Body

​Response

​Download Midia

​Path Parameters

​Headers

​Response

​Mensagens Interativas - Lista

​Path Parameters

​Headers

​Request Body

​Response

​Mensagens Interativas - Botões

​Path Parameters

​Headers

​Request Body

​Response

Arquitetura Positus - WhatsApp Business API

Postman file

messages

Path Parameters

Headers

Request Body

Response

Destinatário: telefone (`to`) ou BSUID (`recipient`)

Request Body (envio para BSUID)

Response (envio para BSUID)

Indicador de digitação

Path Parameters

Headers

Request Body

Response

HSM

Path Parameters

Headers

Request Body

Response

Contact

Path Parameters

Headers

Request Body

Response

Location

Path Parameters

Headers

Request Body

Response

Image

Path Parameters

Headers

Request Body

Response

Document

Path Parameters

Headers

Request Body

Response

Video

Path Parameters

Headers

Request Body

Response

Audio

Path Parameters

Headers

Request Body

Response

Sticker

Path Parameters

Headers

Request Body

Response

Download Midia

Path Parameters

Headers

Response

Mensagens Interativas - Lista

Path Parameters

Headers

Request Body

Response

Mensagens Interativas - Botões

Path Parameters

Headers

Request Body

Response