API - Documentation - Robbu Docs

Positus Architecture - WhatsApp Business API

You can integrate directly with the Positus API (above) or use a customer service platform such as Robbu’s Invenio, without building the integration yourself.

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 for .NET

Production Token: Your token will be generated and provided by Positus; it grants access to all of your WhatsApp Business API numbers. The key will be provided after activation of each WhatsApp Business API number.Sandbox - Development Token: You can generate your token directly through http://studio.posit.us/.

Postman file

The Postman is a tool whose purpose is to test RESTful services (Web APIs) by sending HTTP requests and analyzing their responses. Download Postman App

Production API

Positus API (2026).postman_collection.json

Development API (Sandbox)

Positus API Sandbox (2026).postman_collection.json

messages

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Use this route to send text messages via WhatsApp

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Content-Type	string	application/json
Authorization	string	Authentication using 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": ""
}

Recipient: phone (`to`) or BSUID (`recipient`)

Every message-sending route accepts two ways to identify the recipient. Use one OR the other:

Field	Type	Requirement	Description
`to`	string	Required if `recipient` is omitted	Recipient’s phone number in international format (e.g. `+5511999999999`).
`recipient`	string	Optional — send instead of `to`	Recipient’s BSUID (Business-Scoped User ID) or parent BSUID (e.g. `BR.1234567890`). See BSUID and user identifiers.

The BSUID is a user identifier scoped to the business portfolio, delivered in the user_id field of webhooks. It is useful when the user has adopted a username and the phone number (wa_id) may not be present in the payload. Learn the concept in BSUID and user identifiers.

Precedence when to and recipient coexist: if you send both fields in the same request, the phone number (to) takes precedence — the message is delivered to the phone. Therefore, send only one of them: either to (phone) or recipient (BSUID/parent BSUID).

On-premises numbers accept only to (phone). Sending via recipient (BSUID) is available only for numbers on the Cloud API (Meta).

Request Body (sending to a BSUID)

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

Response (sending to a BSUID)

The response is the same as other sends, but the contacts block — forwarded from Meta — carries the identifier you used in input, along with the phone number (wa_id, when available) and the 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."
        }
    ]
}

Special cases that require a phone number (BSUID not accepted): authentication templates of the one-tap, zero-tap and copy-code types. In these cases, always provide to (phone). If you send a BSUID where it is not supported, Meta responds with error 131062.

Typing indicator

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages/typing-indicator Displays the “typing…” indicator to the customer and marks the received message as read. Provide the message_id of the message sent by the customer. The indicator is automatically dismissed after about 25 seconds or as soon as you reply.

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using Bearer Token
Content-Type	string	application/json

Request Body

Name	Type	Description
message_id	string	Required. ID of the message received from the customer.

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

Response

200
Error

{
    "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 Use this route to send notification messages via WhatsApp HSM - These are message templates pre-approved by Facebook; they can be text, media, or file messages.

The recipient can be provided by phone (to) or by BSUID (recipient), as described in Recipient: phone (to) or BSUID (recipient). Exception: authentication templates of the one-tap, zero-tap and copy-code types require the phone (to) and do not accept BSUID.

Path Parameters

Name	Type	Description
Chave	string

Headers

Name	Type	Description
Authorization	string	Authentication using 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 Share contacts

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using 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 Share locations

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using 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 Share images

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using 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 Share documents

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using 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 Share videos

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using 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 Share audios

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using 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 Share stickers. The sticker format must be exactly 512x512

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using 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"
}

Upload Media

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/send-media Uploads a file to Meta and returns the media ID. Use this ID in the id field of media messages (image, document, video, audio, sticker) when you do not want to expose a public URL in the link field.

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using Bearer Token
Content-Type	string	multipart/form-data

Request Body

The request is multipart/form-data, with the file in the media field.

Name	Type	Description
media	file	Required. File to upload. Maximum size of 16000 KB (approximately 16 MB).

curl -X POST "https://api.positus.global/v2/whatsapp/numbers/{{chave}}/send-media" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "media=@/path/to/file.pdf"

Positus validates only the file size. The accepted types are defined by Meta according to the message type you intend to send (for example, image/jpeg, image/png, application/pdf, video/mp4, audio/ogg). A file of an unsupported type is refused by Meta and returns 422.

Response

The id field is the media ID at Meta, ready to be used when sending messages.

{
    "id": "1234567890123456"
}

Meta refused the upload. The error object is forwarded exactly as returned by Meta.

{
    "error": {
        "message": "(#100) Invalid parameter",
        "type": "OAuthException",
        "code": 100,
        "fbtrace_id": "..."
    }
}

Example of sending a message using the returned id:

{
  "to": "+5511999999999",
  "type": "document",
  "document": {
    "id": "1234567890123456",
    "filename": "contract.pdf"
  }
}

The media ID is temporary at Meta. Upload the file and send the message right after, without storing the ID for long periods.

Get Media by ID

GET https://api.positus.global/v2/whatsapp/numbers/{{chave}}/media-by-id/{{messages.type.id}} Returns the media metadata as JSON, including a Positus URL to download the file.

Difference from Download Media:

GET /media/{{id}} returns the binary content of the file, with the matching Content-Type.
GET /media-by-id/{{id}} returns a JSON with id, url, mime_type, sha256, size, and messaging_product. Use this route when you prefer to receive a link to download the file later instead of receiving the bytes in the response itself.

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number
id	string	Media ID at Meta (received in the webhook or returned by Upload Media)

Headers

Name	Type	Description
Authorization	string	Authentication using Bearer Token

Response

{
    "id": "1234567890123456",
    "url": "https://storage.positus.global/messenger/...",
    "mime_type": "image/jpeg",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb924...",
    "size": 245678,
    "messaging_product": "whatsapp"
}

Media not found or already expired at Meta. The body is the error returned by Meta.

{
    "error": {
        "message": "Unsupported get request. Object with ID '1234567890123456' does not exist",
        "type": "GraphMethodException",
        "code": 100,
        "fbtrace_id": "..."
    }
}

Request limit reached at Meta. The response includes the Retry-After header (in seconds) indicating when to try again.

{
    "message": "..."
}

The media was found at Meta, but downloading the file failed. The body carries the metadata returned by Meta.

{
    "id": "1234567890123456",
    "url": "https://lookaside.fbsbx.com/...",
    "mime_type": "image/jpeg",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb924...",
    "file_size": 245678,
    "messaging_product": "whatsapp"
}

Field	Type	Description
`id`	string	Media ID at Meta.
`url`	string	Positus URL to download the file.
`mime_type`	string	File type (for example, `image/jpeg`, `application/pdf`).
`sha256`	string \| null	Hash informed by Meta. Comes as `null` when the media was already stored at Positus.
`size`	integer	File size in bytes.
`messaging_product`	string	Always `whatsapp`.

If the media has already been downloaded before, Positus responds straight from its own storage, without calling Meta. In that case the sha256 field comes as null. Otherwise, Positus fetches the media from Meta, stores the file, and returns the complete metadata.

The media ID at Meta is ephemeral and each query consumes the application request quota. Download and keep the file in your application instead of querying the same ID repeatedly. When Meta responds 429, respect the Retry-After header before trying again.

Download Media

GET https://api.positus.global/v2/whatsapp/numbers/{{chave}}/media/{{messages.type.id}} Download the media files. Use the media id received in the webhook notification.

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number
id	string	Media ID (received in the webhook)

Headers

Name	Type	Description
Authorization	string	Authentication using Bearer Token

Response

Returns the binary content of the media, with the Content-Type header matching the file type (e.g., image/jpeg, audio/ogg, application/pdf).

Request limit reached at Meta. The response includes the Retry-After header (in seconds) indicating when to try again.

{
    "message": "..."
}

Interactive Messages - List

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages List Messages: Messages including a menu of up to 10 options. This type of message offers a simpler and more consistent way for users to make a selection when interacting with a business. List or reply button messages cannot be used as notifications. Currently, they can only be sent within 24 hours of the last message sent by the user. If you try to send a message outside the 24-hour window, you will receive an error message.

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using 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"
}

Full documentation: https://developers.facebook.com/docs/whatsapp/guides/interactive-messages

Interactive Messages - Buttons

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Reply buttons: Messages including up to 3 options — each option is a button. This type of message offers a faster way for users to make a selection from a menu when interacting with a business. Reply buttons provide the same user experience as interactive templates with buttons. List or reply button messages cannot be used as notifications. Currently, they can only be sent within 24 hours of the last message sent by the user. If you try to send a message outside the 24-hour window, you will receive an error message.

Path Parameters

Name	Type	Description
Chave	string	Unique code per WhatsApp number

Headers

Name	Type	Description
Authorization	string	Authentication using 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"
}

Full documentation: https://developers.facebook.com/docs/whatsapp/guides/interactive-messages

​Positus Architecture - WhatsApp Business API

​Postman file

Production API

Development API (Sandbox)

​messages

​Path Parameters

​Headers

​Request Body

​Response

​Recipient: phone (to) or BSUID (recipient)

​Request Body (sending to a BSUID)

​Response (sending to a BSUID)

​Typing indicator

​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

​Upload Media

​Path Parameters

​Headers

​Request Body

​Response

​Get Media by ID

​Path Parameters

​Headers

​Response

​Download Media

​Path Parameters

​Headers

​Response

​Interactive Messages - List

​Path Parameters

​Headers

​Request Body

​Response

​Interactive Messages - Buttons

​Path Parameters

​Headers

​Request Body

​Response

Positus Architecture - WhatsApp Business API

Postman file

messages

Path Parameters

Headers

Request Body

Response

Recipient: phone (`to`) or BSUID (`recipient`)

Request Body (sending to a BSUID)

Response (sending to a BSUID)

Typing indicator

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

Upload Media

Path Parameters

Headers

Request Body

Response

Get Media by ID

Path Parameters

Headers

Response

Download Media

Path Parameters

Headers

Response

Interactive Messages - List

Path Parameters

Headers

Request Body

Response

Interactive Messages - Buttons

Path Parameters

Headers

Request Body

Response