# API - Documentation

## **Positus Architecture** - WhatsApp Business API

![](https://790634147-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M5N7bAOOZYnLOa5zHg_%2F-MDX_S2nqrsY6NbRpW4a%2F-MDXa19gj5Y94Y9jqkiS%2FPositus%20-%20Arq%20Whats%20Business%20\(Final\)%2002.png?alt=media\&token=2c273689-d25f-4395-a9b3-4fedd463085c)

| SDK                                                         |                        |                                                        |
| ----------------------------------------------------------- | ---------------------- | ------------------------------------------------------ |
| <https://github.com/positusapps/positus-api-laravel-client> | Laravel / PHP          | Youtube                                                |
| <https://github.com/positusapps/positus-api-php-client>     | PHP                    | [Youtube](https://www.youtube.com/watch?v=6hhHz73bsc4) |
| <https://www.nuget.org/packages/positus-api-csharp-client/> | Nuget .NET / .NET Core | [YouTube](https://www.youtube.com/watch?v=E8MZWwfQSZY) |
| <https://github.com/positusapps/positus-api-csharp-client>  | Github para .NET       |                                                        |

{% hint style="info" %}
**Production Environment:** Your token will be generated and provided by Positus, it will give access to all your WhatsApp Business API numbers. MediaId will be provided after activation of each WhatsApp Business API number. \
\
**Sandbox (Development environment):** You can generate your token directly at <http://studio.posit.us/>.
{% endhint %}

## Postman file

*Postman is a tool that aims to test RESTful services (Web APIs) by sending HTTP requests and analyzing their feedback.*\
[Download Postman App](https://www.postman.com/downloads/)

{% file src="<https://790634147-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M5N7bAOOZYnLOa5zHg_%2F-MKochXvjZfxW_h44ex6%2F-MKoclI6z48EbtYJLasN%2FPositus%20API%20(October%202020).postman_collection.json?alt=media&token=7e30899a-eb58-459d-a322-fa3679a2a83b>" %}
API for production
{% endfile %}

{% file src="<https://790634147-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M5N7bAOOZYnLOa5zHg_%2F-MLmCvsSkYdlcK7iyCoM%2F-MLmD-Py-8N10BEFvDt1%2FPositus%20API%20Sandbox%20(November%202020).postman_collection.json?alt=media&token=6878781e-5fd7-49e2-86f9-f69e37ce565b>" %}
API for development SandBox
{% endfile %}

## messages

<mark style="color:green;">`POST`</mark> `https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages`

Utilize this route to send text messages via WhatsApp

#### Path Parameters

| Name  | Type   | Description                    |
| ----- | ------ | ------------------------------ |
| chave | string | Unique code by WhatsApp number |

#### Headers

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

#### Request Body

| Name | Type   | Description                                                                            |
| ---- | ------ | -------------------------------------------------------------------------------------- |
|      | object | { "to": "+5511999999999", "type": "text", "text": { "body": "your-message-content" } } |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

## HSM

<mark style="color:green;">`POST`</mark> `https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages`

Utilize this route to send notification messages via WhatsApp\
HSM - Are message templates that are pre-approved by Facebook, can be text messages, media, or files.

#### Path Parameters

| Name  | Type   | Description                    |
| ----- | ------ | ------------------------------ |
| chave | string | Unique code by WhatsApp number |

#### Headers

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

#### Request Body

| Name    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Full    | string | { "to": "+551199999999", "type": "template", "template": { "namespace": "xxxxxxx", "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" } ] } ] } } |
| Buttons | string | { "to": "+5511999999999", "type": "template", "template": { "namespace": "dc730af3\_d5a86", "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" } ] } }                                                                                                                                                                                                                                                                                                                                        |
| Text    | object | <p>{ "to": "+55119999999999", "type": "hsm", "hsm": { "namespace": "52\_2bca4fad4c4a", "element\_name": "fgv\_3", "language": { "policy": "deterministic", "code": "pt\_BR" }, "localizable\_params": \[ { "default": "Thiago" } ] }<br>}</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

## Contact

<mark style="color:green;">`POST`</mark> `https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages`

Share contacts

#### Path Parameters

| Name  | Type   | Description                    |
| ----- | ------ | ------------------------------ |
| chave | string | Unique code by WhatsApp number |

#### Headers

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

#### Request Body

| Name | Type   | Description                                                                                                                                                                                                                                                                                                          |
| ---- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|      | object | { "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": \[] }] } |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

## Location

<mark style="color:green;">`POST`</mark> `https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages`

Share location

#### Path Parameters

| Name  | Type   | Description                     |
| ----- | ------ | ------------------------------- |
| chave | string | Unique code by WhatsApp numbers |

#### Headers

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

#### Request Body

| Name | Type   | Description                                                                                                                                                                                                      |
| ---- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|      | object | { "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" } } |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

## Image

<mark style="color:green;">`POST`</mark> `https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages`

Share images

#### Path Parameters

| Name    | Type   | Description                    |
| ------- | ------ | ------------------------------ |
| MediaId | string | Unique code by WhatsApp number |

#### Headers

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

#### Request Body

| Name | Type   | Description                                                                                                                        |
| ---- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
|      | object | {  "to": "+5511999999999", "type": "image", "image": { "link": "<https://picsum.photos/200>", "caption": "your-document-caption" } |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

## Document

<mark style="color:green;">`POST`</mark> `https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages`

Share images

#### Path Parameters

| Name  | Type   | Description                    |
| ----- | ------ | ------------------------------ |
| chave | string | Unique code by WhatsApp number |

#### Headers

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

#### Request Body

| Name | Type   | Description                                                                                                                                          |
| ---- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|      | object | {  "to": "+5511941489395", "type": "document", "document": { "link": "<http://www.pdf995.com/samples/pdf.pdf>", "caption": "your-document-caption" } |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

## Video

<mark style="color:green;">`POST`</mark> `https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages`

Share videos&#x20;

#### Path Parameters

| Name  | Type   | Description                    |
| ----- | ------ | ------------------------------ |
| chave | string | Unique code by WhatsApp number |

#### Headers

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

#### Request Body

| Name | Type   | Description                                                                                                                                                                             |
| ---- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|      | object | {  "to": "+5511999999999", "type": "video", "video": { "link": "<https://sample-videos.com/video123/mp4/720/big\\_buck\\_bunny\\_720p\\_1mb.mp4>", "caption": "your-document-caption" } |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

## Audio

<mark style="color:green;">`POST`</mark> `https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages`

Share audio

#### Path Parameters

| Name  | Type   | Description                    |
| ----- | ------ | ------------------------------ |
| chave | string | Unique code by WhatsApp number |

#### Headers

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

#### Request Body

| Name | Type   | Description                                                                                                                |
| ---- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
|      | object | { "to": "+5511999999999", "type": "audio", "audio": { "link": "<https://sample-videos.com/audio/mp3/crowd-cheering.mp3>" } |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

## Sticker

<mark style="color:green;">`POST`</mark> `https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages`

Share stickers. Sticker format must be exactly 512x512

#### Path Parameters

| Name  | Type   | Description                    |
| ----- | ------ | ------------------------------ |
| chave | string | Unique code by WhatsApp number |

#### Headers

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

#### Request Body

| Name | Type   | Description                                                                                                              |
| ---- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
|      | object | { "to": "+5511999999999", "type": "sticker", "sticker": { "link": "<https://studio.posit.us/api/samples/sticker.webp>" } |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

## Download Media

<mark style="color:blue;">`GET`</mark> `https://api.positus.global/v2/whatsapp/numbers/{{chave}}/media/{{messages.type.id}}`

Download media

#### Path Parameters

| Name  | Type   | Description                    |
| ----- | ------ | ------------------------------ |
| chave | string | Unique code by WhatsApp number |

#### Headers

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

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

## Mensagens Interativas - Lista

<mark style="color:green;">`POST`</mark> `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 company.\
\
List button or reply 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 | Código único por número de WhatsApp |

#### Headers

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

#### Request Body

| Name | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|      | string | {"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"}]}]}}} |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Complete documentation: <https://developers.facebook.com/docs/whatsapp/guides/interactive-messages>
{% endhint %}

## Mensagens Interativas - Botões

<mark style="color:green;">`POST`</mark> `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 company. Response buttons have the same user experience as interactive button models.\
\
List button or reply 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 | Código único por número de WhatsApp |

#### Headers

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

#### Request Body

| Name | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|      | string | {"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](https://docs.en.posit.us/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"}}]}}} |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Complete documentation: <https://developers.facebook.com/docs/whatsapp/guides/interactive-messages>
{% endhint %}