WhatsApp Integration API

Download OpenAPI specification:Download

Version Version date
alpha 2021-06-24

WhatsApp Integration API allows you to use your WhatsApp Business Account with many messaging solution concurrently. It allows you to integrate your favorite chat solution, with any chatbot or CRM you prefer.

Introduction

A missing puzzle piece

APIs
Our API and Inbox together make a missing puzzle piece you always needed.

WhatsApp Integration API and Web Inbox act as an extension layer for WhatsApp Business API (WABA). Here is a list of benefits of using both of the solutions:

Feature Web Inbox WhatsApp Integration API WABA
Connect unlimited simultaneous apps to your WA Business account N/A
Graphical user interface for you and your employees N/A
Multi-user access to sending and receiving of your WA Business account messages
Search within the last 1 mio messages
Deeplinking into message threads
Synchronize each app (or system) separately
  • Push messages from WABA to each app (or system) separately using separate webhook or websockets
  • Push messages from each app (or system) to WABA, preserving the information which app or system or real user (Inbox) has sent the message
N/A

FAQ

How is WhatsApp Integration API different from other integration platforms?

It is an integration platform specially designed for WhatsApp Business API, focusing only on functions around WhatsApp and typical solutions integrating into WhatsApp. Every number has its own database and the Integration API syncs incoming messages actively into all integrated solutions.

Where are messages stored?

Messages are stored in an own database per number in the Integration API until a threshold of 1 Million messages is reached. So different accounts do not share the same database.

Which limitations does the system have?

Message volume is limited on 1 mio messages. System does not have it’s own routing system or rule engine.

Is a search index part of the Integration API or is an external solution needed?

Search for up to 1 Million messages is supported, but when search function for more messages is needed, then an external search index is needed to be used.

How can routing rules be applied to the system

Routing rules are manageable either through CRM or ticketing solution or through any external rule engine.

Which functions apply to the Integration API?

The Web Inbox is just a frontend of the Integration API. There are not (yet) any additional functions on the frontend level.

Accessing the API

Base URL

Entire docs are written with relation to this specific inbox.

Your inbox is reachable at https://your.base.url.com/ and all API endpoints are reachable at https://your.base.url.com/api/v1/.

If that is not your inbox, or you are using this inbox as an example, please consult us to receive your own base URL first and then use it with a combination of paths given in the docs.

For example, sending a POST to /api/v1/auth/token/ means sending a POST to https://your.base.url/api/v1/auth/token which for this particular inbox is equal to https://your.base.url.com/api/v1/auth/token/.

Different base URL for each inbox is connected to providing separate servers and databases for your inbox, so that all your data is well isolated from other inboxes.

Authorization

Currently, there are three ways of authorization available:

Token authorization is designed for accessing the API from your own services / apps / chatbots.

Session authorization mechanism is what is used by default when logging into the admin panel.

Provider authorization can be used when you need to log in using WABA Stack provider credentials (360dialog).

See below sections for more details.

Token

Token authorization should be preferred.

Each of your service or app or chatbot that will reach the API needs to have its own User account and authorization token bound to the account.

This type of authorization is done with Authorization: Token <token> header, where <token> value needs to be obtained first.

To obtain a token, send POST to /api/v1/auth/token/ with username and password fields either as JSON fields or POST data.

Example:

curl -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST \
    https://your.base.url.com/api/v1/auth/token/ \
    --data "{\"username\": \"peter\", \"password\": \"secret\"}"

When valid username and password are provided, API will send you a (new or existing available) token in JSON body field token, for example:

{"token": "8aeb44f5a318542d32bb13019d68198467ee21f0"}

Make sure all authorization requests are done via HTTPS connection, otherwise username and password are not encrypted.

Session

Each accessible page will provide to you with CSRF token, for example:

HTTP/1.1 200 OK
Set-Cookie:  csrftoken=TezohQtkhqw03yaiSOyvOVFymCeIm3VfdYKLkaG33DWz0lgR7nVroQREeV3Hj3Rw; expires=Thu, 20 Jan 2022 11:19:51 GMT; Max-Age=31449600; Path=/; SameSite=Lax

API endpoints are not accessible until you authorize (either by token or session), but several pages are accessible without authorizing. For example, you can send a GET request to /api/v1/ and obtain token this way.

This unique token identifies you, so that's why it should be saved as cookie and then used later on in further requests.

After logging in via official form /login/, you will obtain sessionid too, for example:

HTTP/1.1 302 Found
Set-Cookie: csrftoken=mc73th9HxjMpy5UuCC3981LZeE0jt8sH4i8Md8BZoy9Agygv9M7WimALSVXCV1hL; expires=Thu, 20 Jan 2022 14:48:54 GMT; Max-Age=31449600; Path=/; SameSite=Lax
Set-Cookie: sessionid=mdsxd9cczt27tp2d806hfi245emmxuvk; expires=Thu, 04 Feb 2021 14:48:54 GMT; HttpOnly; Max-Age=1209600; Path=/; SameSite=Lax

These two cookies identify you as a logged in user. Thanks to them no 'Authorization' header is needed, but Cookie header should be used instead with above cookies.

Provider

Provider authorization can be used when you need to log in using WABA Stack provider credentials (360dialog).

To authenticate using Provider method, provide 360dialog API Key header when calling the API.

For example:

curl -H "D360-Api-Key: xEZOvMBDS6zEZtbR2xCJkP5R75szhCUIvMH" \
     -H "Accept: application/json" \
     -X GET \
     https://your.base.url.com/api/v1/users/current/

Integration API will then reach to 360dialog and will ask 360dialog systems if the key is valid.

If the provided D360-Api-Key is valid, you will be authenticated as Integration API admin User. If there are more than one admin group members, you will be authenticated as the admin User that was registered when the inbox was created for the first time. If said User is no longer active or was removed, this method will authenticate you as an admin User of following conditions:

  • this User's account is still active (when you decide a particular User should no longer have the access, User accounts are marked as inactive instead of removed)
  • this User's account creation date is the oldest

If provided API Key is invalid, this method will silently fail and then Token and Session auth methods will be checked. That means if invalid D360-Api-Key is the only authorization data provided, you will see a following response:

HTTP/1.1 403 Forbidden
{"detail":"Authentication credentials were not provided."}

Note that above example calls Retrieve Current User endpoint and will show you the exact account that was authenticated during your request. For example:

curl -H "D360-Api-Key: xEZOvMBDS6zEZtbR2xCJkP5R75szhCUIvMH" \
     -H "Accept: application/json" \
     -X GET \
     https://your.base.url.com/api/v1/users/current/ \
    | python -m json.tool

{
    "url": "https://your.base.url.com/api/v1/users/2/",
    "id": 2,
    "username": "peter",
    "first_name": "Peter",
    "last_name": "Rabbit",
    "email": "peter@example.com",
    "profile": {
        "role": "admin"
    },
    "groups": [
        {
            "id": 3,
            "name": "Admin"
        }
    ],
    "permissions": {
        "can_use_tags": true,
        "can_read_chats": "all",
        "can_write_to_chats": "all"
    }
}

Making requests

Each endpoint described later in the docs has to be accessed with HTTP Request +SSL and either with Token or Session based authorization.

When making POST requests, JSON data specified in the docs has to be sent as POST data payload.

Example for GET request with curl:

(Replace all https://your.base.url.com/ URLs in this doc with the actual base URL of your Wabbit Integration API)

curl \
    -H "Authorization: Token 8aeb44f5a318542d32bb13019d68198467ee21f0" \
    -X GET \
    https://your.base.url.com/api/v1/chats/ \
    -H "Accept: application/json"

Example for POST request with curl:

curl -H "Authorization: Token 8aeb44f5a318542d32bb13019d68198467ee21f0" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST \
    https://your.base.url.com/api/v1/messages/ \
    --data "{\"wa_id\": \"48123456789\", \"text\": {\"body\": \"Hello!\"}}"

Note that our API supports passing request payload parameters as either POST data application/json, application/x-www-form-urlencoded or multipart/form-data.

Getting started

You should start with /chats/ endpoint:

curl -H "Authorization: Token 8aeb44f5a318542d32bb13019d68198467ee21f0" \
    -X GET \
    https://your.base.url.com/api/v1/chats/ \
    | python -m json.tool

[
    {
        "wa_id": "48500500500",
        "new_messages": 11
    },
    {
        "wa_id": "4912312312312",
        "new_messages": 0
    },
    {
        "wa_id": "90123123123",
        "new_messages": 22
    }
]

Read more about /chats/ endpoint here.

You can use python -m json.tool to make the output more readable, but it is not necessary.

Above response makes it clear how many new messages you have and where to find them.

You can read each contact messages like this:


curl -H "Authorization: Token 8aeb44f5a318542d32bb13019d68198467ee21f0" \
    -X GET \
    https://your.base.url.com/api/v1/messages/?wa_id=48123123123&limit=1 \
    | python -m json.tool

{
    "count": 276,
    "next": "http://your.base.url.com/api/v1/messages/?wa_id=48123123123/&limit=1&offset=1",
    "previous": null,
    "results": [
        {
            "waba_payload": {
                "from": "48123123123",
                "id": "ABGGSFEBeRJ_AhD8o8zP9ulNeUPgdKvfzvgh",
                "timestamp": "1612544982",
                "type": "video",
                "video": {
                    "id": "20854d67-189e-4e78-a8ac-123sdf234ad",
                    "mime_type": "video/mp4",
                    "sha256": "da7f4ab0b60e7df1d1e8b0537bcdec3a86d605e79fa28333c4c1dc50561d86ac",
                    "link": "http://your.base.url.com/api/v1/media/20854d67-189e-4e78-a8ac-123sdf234ad/"
                }
            },
            "customer_wa_id": "48123123123",
            "from_us": false,
            "received": false,
            "sender": null
        }
    ]
}

Read more about /messages/ endpoint here. The main payload of the message is waba_payload JSON field, which copies data returned by WhatsApp Business API. In waba_payload you will always have information about type of the message, id, from and timestamp.

In above example, a limit=1 query parameter was used, so that only one message is returned, for readability of this tutorial. In reality, you will be reading messages in batches, for example 20 messages:

curl -H "Authorization: Token 8aeb44f5a318542d32bb13019d68198467ee21f0" \
    -X GET \
    https://your.base.url.com/api/v1/messages/?wa_id=48123123123&limit=20

This endpoint returns to you most recent messages, ordered from newest to oldest.

Then, if you want to read next 20 (older) messages, you need to use before_time query parameter, indicating the POSIX timestamp of the last message you had before (in previous batch). The API will then return 20 messages before given timestamp:

curl -H "Authorization: Token 8aeb44f5a318542d32bb13019d68198467ee21f0" \
    -X GET \
    https://your.base.url.com/api/v1/messages/?wa_id=48123123123&limit=20&before_time=1612544982

The default pagination method is implemented as offset and limit params in most of the endpoints. But for this endpoint, before_time is provided, to be able to paginate elements correctly, even when new messages arrive at the time of pagination.

Whenever you think you no longer need these messages being indicated as new (in our first /chats/ call) you can mark these messages as received. Marking messages as received by you is needed to generate proper lists of unread messages.

You can mark messages as received in three ways:

  1. Use /mark_as_received/ endpoint.
  2. Use mark_as_received parameter of /messages/ endpoint.
  3. Use WABA Webhook

The choice of method depends on your use case. For example, first method is useful when you prefetch these messages and then you make sure whether user received them or not (for example a web based app or mobile app). Second method, on the other hand, is handy when you are just passing messages from our inbox to some other system.

It is required to use one of above methods if you want to keep track of what was already received by your users, bots or any integrated systems. You want to keep track of it basically always, for example:

  • when you implement any kind of indication of new/unread messages (on the frontend or in any other way)
  • when you simply forward messages to your system in batches and would like to receive only fresh messages on each iteration

WABA Webhooks take care of it for you. It works the "old way" you should be familiar with if you used WhatsApp Business API before.

Integration

WABA Webhook

WhatsApp Integration API provides a (de)multiplexing solution of original WhatsApp Business API (WABA) webhook. WABA itself allows you to integrate only one webhook. With our API you can set up multiple per-user webhooks.

Webhooks
How Webhooks are created and used

How to read above picture: Integration API provides Webhooks as a resource. Then you (manually), or your app (automatically) can create and delete Webhooks. In above example, your chatbot solution can create a Webhook, using proper username+password credentials. Then, Webhook calls your chatbot solution endpoint, triggered by specific events like incoming messages or status updates.

Multiple Webhooks
How Multiple Webhooks are called

Each WABA Webhook is configured per API user - Your Chatbot, Your CRM System etc. One user can have only one WABA Webhook config. When WABA webhook calls our API, all created Webhooks are triggered and each of them is calling your configured endpoints.

You are not required to set up one webhook per one app (or system). If you want, you can configure only one webhook for all your apps, and then distribute messages and notifications to your apps yourself. One webhook per app however is the recommended method.

See following endpoints to learn more on how to manage your WABA Webhooks:

Correctly configured WABA Webhook will propagate webhooks incoming from WABA to each of your endpoints. Propagated webhook call will be exactly the same POST call as original WhatsApp Business API webhook:

POST /

{
  "contacts": [ {
    "profile": {
        "name": "sender-profile-name"
    },
    "wa_id": "wa-id-of-contact"
  } ],
  "messages": [ {
    "context": {
         "from": "sender-wa-id-of-context-message",
         "id": "message-id-of-context-message",
         "mentions": [ "wa-id1", "wa-id2" ],
         "forwarded": true | false,
         "frequently_forwarded": true | false
    },
    "from": "sender-wa-id",
    "id": "message-id",
    "timestamp": "message-timestamp",
    "type": "audio | document | image | location | system | text | video | voice",

    # If there are any errors the errors field (array) will be present.
    # The errors field can be returned as part of any callback event.
    "errors": [ { ... } ],

    "audio": {
        "file": "absolute-filepath-on-coreapp",
        "id": "media-id",
        "link": "link-to-audio-file",
        "mime_type": "media-mime-type",
         "sha256": "checksum"
    }

    "document": {
        "file": "absolute-filepath-on-coreapp",
        "id": "media-id",
        "link": "link-to-document-file",
        "mime_type": "media-mime-type",
        "sha256": "checksum",
        "caption": "document-caption"
    }

    "image": {
        "file": "absolute-filepath-on-coreapp",
        "id": "media-id",
        "link": "link-to-image-file",
        "mime_type": "media-mime-type",
        "sha256": "checksum",
        "caption": "image-caption"
    }

    "location": {
        "address": "1 Hacker Way, Menlo Park, CA, 94025",    
        "latitude": latitude,
        "longitude": longitude,
        "name": "location-name"
    }

    "system": {
        "body": "system-message-content"
    }

    "text": {
        "body": "text-message-content"
    }

    "video": {
        "file": "absolute-filepath-on-coreapp",
        "id": "media-id",
        "link": "link-to-video-file",
        "mime_type": "media-mime-type",
        "sha256": "checksum"
    }

    "voice": {
        "file": "absolute-filepath-on-coreapp",
        "id": "media-id",
        "link": "link-to-audio-file",
        "mime_type": "media-mime-type",
        "sha256": "checksum"
    }
  ]
}

WABA Webhook extension

Official WhatsApp Business API Webhook definition, provides three fields: "contacts", "messages" and "statuses" fields. Our Integration API adds several new fields to this set, which has following benefits:

  • It keeps backward compatibility, leaving original fields unchanged.
  • Provides more flexibility, allowing you to receive all available events at yor single endpoint, or to distribute each event to a separate endpoint, depending on your use case and needs.

Below is a description of all new fields and when to expect them:

  • "incoming_messages" will show up always when original/official WhatsApp Business API Webhook is called. Any API User that is configured to receive all incoming Messages, will receive a webhook containing both "messages" field (with exactly the same list of objects that are sent by WABA Stack) and our new "incoming_messages" field.

  • "outgoing_messages" will show up whenever one of the Inbox Users writes a new Message and WABA Webhook recipient is configured to receive all outgoing Messages. This field contains only messages sent from Wabbit Inbox by your inbox Users.

  • "assigned_messages" will show up whenever new Messages arrive to the Chat that is currently assigned to the User receiving this Webhook and also when one or more Chats are assigned to the User just now. It is important to note that Messages are never assigned to Users. Only Chats are assigned to inbox Users. This field name might then look misleading, however the true meaning of this field is not "assigned messages" but "new Messages from an assigned Chat". Provided name is just shorter.

  • "chat_assignment" will show up for all webhook receivers whenever someone changes an assignment of a Chat either via API or Web App.

  • "chat_tagging" will show up for all webhook receivers each time any Message is tagged or tagging is removed. This event is also send to Rule Engine. Learn more about Rule Engine.

  • "message_tagging" will show up for all webhook receivers each time any Chat is tagged or tagging is removed. Keep in mind that when a Message is tagged with a Tag, then a corresponding Chat is tagged with the same Tag immediately! This event is also send to Rule Engine. Learn more about Rule Engine.

  • "tagged_messages" deprecated

  • "tagged_chats" deprecated

WhatsApp Business API does not call your webhook with outgoing messages, but we do!

Each field has its own schema defined below:

  • "incoming_messages" | "outgoing_messages" | "assigned_messages" - a JSON Array of Object elements of exactly the same schema as in get List Messages API endpoint (results Array entries).

  • "chat_tagging" - a JSON Object of exactly the same schema as in get List Chat Tagging Events API endpoint (results Array entries).

  • "message_tagging" - a JSON Object of exactly the same schema as in get List Message Tagging Events API endpoint (results Array entries).

  • "chat_assignment" - a JSON Object of exactly the same schema as in get List Chat Assignment Events API endpoint (results Array entries).

  • "tagged_messages" deprecated - a JSON Array of Object elements containing "message" and "tag" fields:

    • "message" - Object of exactly the same schema as in get List Messages API endpoint (results Array entries).
    • "new_tag" - Object containing data of a new Tag applied to the Message:
      • "name" - String Tag name
      • "id" - Integer Tag ID
      • "extra" - Object optional field containing any kind of extra meta-data provided by one of your integrated bots or apps.
  • "tagged_chats" deprecated - a JSON Array of Object elements containing "chat" and "tag" fields:

    • "chat" - Object of exactly the same schema as in get List Chats API endpoint (results Array entries).
    • "new_tag" - Object containing data of a new Tag applied to the Chat:
      • "name" - String Tag name
      • "id" - Integer Tag ID
      • "extra" - Object optional field containing any kind of extra meta-data provided by one of your integrated bots or apps.

Example payload of a Webhook call containing either "outgoing_messages" or "assigned_messages" field:

POST /

{
  "outgoing_messages": [
        {
            "waba_payload": {
                "preview_url": false,
                "recipient_type": "individual",
                "to": "48123123123",
                "type": "image",
                "image": {
                    "link": "http://your.base.url.com/api/v1/media/e4b60f1d-1847-4233-8a88-58e123123123"
                },
                "id": "gBGGSFEBeRJ_AglpKKJ1s123123",
                "timestamp": 1612372697
            },
            "waba_statuses": {
                "sent": 0,
                "delivered": 0,
                "read": 0
            },
            "contact": {
                "wa_id": "48123123123",
                "waba_payload": {
                    "profile": {
                        "name": "Konrad Tester"
                    },
                    "wa_id": "48123123123"
                },
                "initials": "KT",
                "last_message_timestamp": 1613398401
            },
            "from_us": true,
            "received": true,
            "sender": {
                "url": "http://your.base.url.com/api/v1/users/1/",
                "id": 1,
                "username": "konrad",
                "first_name": "Konrad",
                "last_name": "Tester",
                "email": "konrad@example.com",
                "profile": {
                    "role": "admin"
                }
            },
            "context": null,
            "customer_wa_id": "48123123123"
        },
        {
            "waba_payload": {
                "preview_url": false,
                "recipient_type": "individual",
                "to": "48123123123",
                "type": "image",
                "image": {
                    "link": "http://your.base.url.com/api/v1/media/bc4bd93e-a522-4bce-aac8-cc1123123123"
                },
                "id": "gBGGSFEBeRJ_AgnJK-don123123",
                "timestamp": 1612372571
            },
            "waba_statuses": {
                "sent": 0,
                "delivered": 0,
                "read": 0
            },
            "contact": {
                "wa_id": "48123123123",
                "waba_payload": {
                    "profile": {
                        "name": "Konrad Tester"
                    },
                    "wa_id": "48123123123"
                },
                "initials": "KT",
                "last_message_timestamp": 1613398401
            },
            "from_us": true,
            "received": true,
            "sender": {
                "url": "http://your.base.url.com/api/v1/users/1/",
                "id": 1,
                "username": "konrad",
                "first_name": "Konrad",
                "last_name": "Tester",
                "email": "konrad@example.com",
                "profile": {
                    "role": "admin"
                }
            },
            "context": null,
            "customer_wa_id": "48123123123"
        }
    ]
}

Example payload of a Webhook call containing "tagged_messages" field that will be sent to Rule Engine.

POST /

{
  "tagged_messages": [ {
        "new_tag": {
            "name": "Agent needed",
            "id": 5,
            "extra": {}
        },
        "message": {
            "waba_payload": {
                "preview_url": false,
                "recipient_type": "individual",
                "to": "48123123123",
                "type": "image",
                "image": {
                    "link": "http://your.base.url.com/api/v1/media/e4b60f1d-1847-4233-8a88-58e123123123"
                },
                "id": "gBGGSFEBeRJ_AglpKKJ1s123123",
                "timestamp": 1612372697
            },
            "waba_statuses": {
                "sent": 0,
                "delivered": 0,
                "read": 0
            },
            "contact": {
                "wa_id": "48123123123",
                "waba_payload": {
                    "profile": {
                        "name": "Konrad Tester"
                    },
                    "wa_id": "48123123123"
                },
                "initials": "KT",
                "last_message_timestamp": 1613398401
            },
            "from_us": true,
            "received": true,
            "sender": {
                "url": "http://your.base.url.com/api/v1/users/1/",
                "id": 1,
                "username": "konrad",
                "first_name": "Konrad",
                "last_name": "Tester",
                "email": "konrad@example.com",
                "profile": {
                    "role": "admin"
                }
            },
            "context": null,
            "customer_wa_id": "48123123123",
            "tags": [
                {
                    "name": "agent neded",
                    "web_inbox_color": null,
                    "id": 5,
                    "extra": {}
                }
            ]
        }
    } ]
}

Example payload of a Webhook call containing "tagged_chats" field that will be sent to Rule Engine.

POST /

{
  "tagged_chats": [ {
        "new_tag": {
            "name": "Agent needed",
            "id": 5,
            "extra": {}
        },
        "chat": {
            "contact": {
                "wa_id": "48123123123",
                "waba_payload": {
                    "profile": {
                        "name": "Konrad"
                    },
                    "wa_id": "48123123123"
                },
                "initials": "K",
                "last_message_timestamp": 1613398401
            },
            "new_messages": 0,
            "wa_id": "48123123123",
            "last_message": {
                "waba_payload": {
                    "preview_url": false,
                    "recipient_type": "individual",
                    "to": "48123123123",
                    "type": "image",
                    "image": {
                        "link": "http://your.base.url.com/api/v1/media/bc4bd93e-a522-4bce-aac8-cc1947f12345"
                    },
                    "id": "gBGGSFEBeRJ_AgnJK-donC12345",
                    "timestamp": "1612372571"
                },
                "waba_statuses": {
                    "sent": 0,
                    "delivered": 0,
                    "read": 0
                },
                "contact": null,
                "from_us": true,
                "received": false,
                "sender": {
                    "url": "http://your.base.url.com/api/v1/users/1/",
                    "id": 1,
                    "username": "konrad",
                    "first_name": "Konrad",
                    "last_name": "Tester",
                    "email": "konrad@example.com",
                    "profile": {
                        "role": "admin"
                    }
                },
                "context": null,
                "customer_wa_id": "48123123123",
                "tags": [
                    {
                        "name": "agent neded",
                        "web_inbox_color": null,
                        "id": 5,
                        "extra": {}
                    }
                ]
            }
        }
    } ]
}

Messages marked as received

Our API provides a way of determining whether a specific API User or Inbox User has received the message. This is used in /chats/ endpoint to provide a way of quickly determining which chats have still new messages. This feature is especially useful for frontends like our Web Inbox.

Message "received" status is considered for every API User separately.

Messages delivered via WABA Webhook successfully are automatically marked as received!

Integrating a bot

In order to integrate a bot, you'll need to understand the Rule Engine concept and configure your bot correctly. A Rule Engine is a component that determines when messages should be assigned to real users or bot users. By configuring a Rule Engine, you can direct fresh new messages to a bot first, or you can choose to direct messages only when they are tagged by other users with tags specified by you.

Assuming you already know how Rule Engine works, below is a short explanation on how to connect a bot to your inbox.

To add your bot to the system you need to:

  • Create a new User for your bot using either User API or Admin Panel. If you choose the API, you need to create a new User with profile.role equal to "app". If via Admin Panel, you need to add your new User to "App integration" group. This will provide some security restrictions for your automated (non-human) User.
  • Set up a Webhook for your bot, so that your bot receives a webhook call whenever any of selected events happen. Again, you can create a Webhook via API or Admin Panel. Possible Webhook events are: on incoming message, on outgoing message, on assigned. Read more about when to expect these events and what is the data schema in WABA Webhook extension section.

If you just need a bot that is passively consuming messages and does not participate in any conversation, you can do allright with no Rule Engine configuration being set. In such case, you can create a Webhook that is executed with "on incoming message" event. Then, your bot is not assigned to the related Chat and can passively archive or monitor incoming messages, transparently to all other users of the inbox.

However, if you need to assign a Chat conversation to a bot user, you will need to configure the Rule Engine.

The Rule Engine configuration controls the main flow (or pipelining) of your Messages. If you're not developing your own custom Rule Engine, you should go here and configure the Default Rule Engine to decide when your bot should be assigned to Chats automatically.

In Default Rule Engine config you have two options:

  • To automatically assign your bot to any new Chat (or any new Message coming to an unassigned Chat) you need to create a new Rule and leave the "Tagged with" field blank, then pick your bot User in the field "Assign to user".
  • To automatically assign your bot to a Chat when a Chat is tagged by a specific Tag, you need to create a new Rule like above, providing a specific Tag in "Tagged with" field.

Chats and Messages can be tagged by any API user (and thus bot) with Tags API.

Monitoring or archiving bot example

As explained above, a monitoring/archiving bot does not require too much config. For this example, we will create a new User using Admin Panel and add this User to "App integration" Group. Then we create a WABA Webhook for this User with one of these two events selected: "on incoming message", "on outgoing message", depending on what we want to monitor/archive.

Spam filtering bot example

To create a spam filtering bot that will receive Messages as a very first User, we will configure our Message pipeline using Default Rule Engine.

First, we will create a new User and add this User to "App integration" Group. Then we will create a new Rule and choose this User in "Assign to user" field. By leaving the "Tagged with" field blank, we create a Rule that is executed whenever any fresh new message comes to the Inbox from WhatsApp directly. This Rule makes sure our spam filtering bot is the only recipient of given messages (except Users with read permissions equal to "All Chats").

Above Rule cannot work alone without a Webhook. It can work if you create a Rule for a human User that is logging in to a Web App frontend, but that is not the case here.

So we will create a new Webhook for this User again using Admin Panel. When creating, we need to check the "On assigned" field and only this field.

Then, we will need to create a new Tag that will be used by our bot. Our bot will mark Chats with this Tag as soon as human interaction is needed. Let's create a Tag using Admin Panel and name it "Agent needed". After you create the Tag, you can find the Tag ID in the Tag list or in new Tag details view. Save this ID for later, because our bot will be using this number.

We now need to create a new Rule and set it up so that our bot could pass the Message flow to human inbox users. Let's create a new Rule for our new Tag, so let's pick our "Agent needed" Tag in the "Tagged with" field and let's pick "Regular user" Group in the "Assign to group" field.

After saving this Rule, our Rule Engine will know that as soon as a Chat is tagged with "Agent needed" Tag, Users in Regular user Group need to be notified and will have access to related Messages.

As a result, we will have the following flow:

  1. A new Message is sent from WhatsApp to your Inbox

  2. Wabbit Integration API calls your Rule Engine Webhook with following payload:

    (Irrelevant data hidden for readability)

     {
       "contacts": "...",
       "messages": [ {
         "from": "48123123123",
         "id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60bd",
         "...": "..."
       } ]
     }    
  3. Rule Engine replies with following payload:

    (Assuming the bot User id is 42, for example)

     {
       "assignment": [{
         "message_id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60bd",
         "user": 42
       }]
     }
  4. Wabbit Integration API handles the assignment change and notifies corresponding bot User (user id = 42)

  5. Bot User then receives its own Webhook with following payload:

    (Irrelevant data hidden for readability)

     {
         "assigned_messages": [ {
             "waba_payload": {
                 "from": "48123123123",
                 "id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60bd",
                 "type": "text",
                 "text": {
                     "body": "Hello"
                 },
                 "...": "..."
             },
             "...": "..."
         } ]
     }    
  6. Bot User is then able to reply to the WhatsApp User using Integration API endpoint post Create Message:

    (Irrelevant data hidden for readability)

     {
       "wa_id": "48123123123",
       "type": "text",
       "text": {
         "body": "Hello! How may I help you?"
       }
     }

    IMPORTANT: It is important to use the same wa_id as in received message (assigned_messages.0.waba_payload.from in the 5. step). By default, bot will be able to reply to assigned Chat only.

    NOTE: A bot might use a template message at this point, showing possible action button answers to the user.

  7. The conversation continues as long as bot can handle the message:

    • Incoming Messages sent from WhatsApp to the bot, arrive as Webhooks with "messages" payload
    • Each response from the bot to the WhatsApp User have to be sent as API post Create Message calls
  8. Eventually, bot cannot handle the conversation no more or human interaction is requested by WhatsApp User explicitly. Then, bot User calls the Integration API to tag the message accordingly using post Create Tagging call.

    When a Message is tagged, then the related Chat is tagged as well and this is what executes the Rule Engine Rule. Still, we recommend to tag Messages instead of Chats, to preserve the history of when the flow has changed. You can choose however to tag the Chat directly instead and this flow will work exactly the same.

  9. Because a new Tagging was made, Rule Engine is called again and determines that a Chat tagged with "Agent needed" tag means "Regular user" Group needs to be assigned and notified.

  10. Integration API assigns then this Message Chat to "Regular user" Group and notifies each User in the Group letting them to decide who will be assigned or letting them to continue without any assignment.

    Depending on user group membership, Users may assign themselves to the Chat:

    • by default, they can assign themselves to the Chat they have read access to
    • if in admin group, they can assign themselves and other Users with no restrictions

    Users can also reply to the Chat:

    • if their Group is assigned to this Chat
    • if the User is assigned directly to the Chat

    By default, a User is not allowed to write to Chats they're not directly assigned to.

    If in admin group, the User can write to any existing Chat.

Websockets

A Websockets Server is available at wss://websockets-your.base.url.com/

Note the wss:// means SSL is used and ws:// prefix will not work.

Websockets protocol

Wabbit WhatsApp Integration API Websockets Server communicates with events serialized as JSON data strings.

Websockets protocol allows bi-directional messages, so a message can be either sent by Client (to Server) or by Server (to Client). Our own protocol distinguishes different types of messages, denoted by type field of each message payload. An exception here is a "Token authentication" message. This type of message is always expected as a first message and it's the only type of message allowed to be sent by Client, so the type field is omitted for simplicity.

Check below list of valid message types.

Message type Token authentication
Sent by Client
Description Send this message as your first message to authenticate yourself so that Websockets Server will know you are authorized to receive messages and will register you for future notifications.
Field Description
token String value of your token
Example payload
{"token": "8aeb44f5a318542d32bb13019d68198467ee21f0"}
Message type Server response
Sent by Server
Description Server can "reply" to Client messages with this type of message right after any kind of Client message. As for now, it can happen only after Token authentication type of message, because that's the only type of message that can be sent by Client.
Field Description
type Equal to "response"
status Possible values: "bad_request" - Meaning Client has sent a request of wrong format or value in its previous request.
message Human-readable description of the Server response - for example why Token authentication payload JSON is formatted incorrectly.
Example payload
{
"type": "response",
"status": "bad_request",
"message": "Expecting value: line 1 column 1 (char 0)"
}
Message type Token authentication result
Sent by Server
Description Token authentication result sent after Token authentication Client message
Field Description
type Equal to "token"
status Possible values: "success", "failed"
message Human-readable description of the status
Example payload
{
"type": "token",
"status": "success",
"message": "Welcome, peter!"
}
Example payload
{
"type": "token",
"status": "failed",
"message": "Token matching query does not exist."
}
Message type WABA Webhook
Sent by Server
Description By this event, your Client will receive WABA Webhooks in websockets message payload. For more details on what is placed inside "waba_payload": { object } see WABA Webhook section.
Field Description
type Equal to "waba_webhook"
waba_payload Object of exactly the same format and data as in WABA Webhook payload.
Example payload
{
"type": "waba_webhook",
"waba_payload": { object }
}

Main protocol algorithm looks like this:

  1. Client sends Token authentication message to the Server
    • Eventually, Server response message will be sent to the Client, if previous message payload was wrong format.
  2. Server sends Token authentication result message to the Client
  3. If Token authentication result status is success, Client can now expect and receive future events of WABA Webhook type

WABA Webhook inside websockets

In contrast to HTTP-transferred WABA Webhooks (normal webhooks), webhooks successfully transferred via Websockets are not marking related messages as received by you! This is because of the main reason we provide Webhooks here - to allow building of apps similar to our Web Inbox.

Solutions like Web Inbox frontend will mainly use the WABA Webhook message type for things like message delivery status update.

Rule Engine

A Rule Engine is a component that determines when messages should be assigned to real Users or bot Users.

WhatsApp Integration API distributes Webhooks among different configured recipient Users, as described in WABA Webhook section.

In order to determine which messages go to which Users, Integration API backend communicates with the Rule Engine.

You are able to provide your own custom Rule Engine implementation. If you don't do that, your inbox is running a Default Rule Engine.

Communication with a Rule Engine (either Default or custom) is made on following events:

  • Whenever a new Message arrives from WhatsApp directly to your Inbox, the API backend asks the Rule Engine which User should be assigned to this message
  • Whenever a new Message is created and sent from your Inbox to WhatsApp, the API backend asks the Rule Engine if assignment should be changed now
  • Whenever any existing Message is tagged with a text Tag or advanced metadata, the API backend asks the Rule Engine about assignment as well
  • Whenever any existing Chat is tagged with a text Tag or advanced metadata

When backend receives a response from the Rule Engine, the Integration API takes care of notifying assigned Users with web browser desktop notification (Web App human Users) or Webhooks (integrated apps or bots).

Default Rule Engine

Default Rule Engine allows you to set simple set of User assignment Rules based on Message tagging.

For example, you're able to configure Default Rule Engine to forward fresh new Messages to your bot or spam-filtering solution first, before they go to real customer support or agents.

Then, you can implement your bot or spam-filtering solution so that it tags a specified Message on events like:

  • the bot can no longer continue this conversation, and a real person needs to be involved
  • or spam-filtering solution accepted the message, and it can go forward

You do that by making your bot or spam-filtering solution call Integration API directly and tag related Message or entire Chat. In our example:

  • the bot might tag a Message with a "Agent needed" tag
  • the spam-filtering solution might give a "No spam" tag

When a new tagging is created, the Rule Engine is called again, to determine if any action needs to be taken. In our case:

  • API backend tells Rule Engine that a Message was tagged with "Agent needed" Tag
  • Rule Engine then checks its set of Rules
  • One Rule says that "Agent needed" Tag message should be assigned to one of the Users in "Agents" Group
  • Rule Engine replies with one of the Users from the "Agents" user Group

You can configure the Default Rule Engine here.

Wabbit Inbox settings allow defining read/write (or receive/send) permissions to Users and user Groups, based on assignment. Thanks to that, you can easily configure:

  • if a User is allowed to write to a Chat they are assigned to (by default: you can write to Chats you are assigned to)
  • if a User is allowed to read from Chats assigned to other members of the same Group (by default: you can read from Chats assigned to other members of your Group)
  • if a User is allowed to write to Chats assigned to other members of the same Group (by default: you're not allowed to write to Chats assigned to another User)

Go to permission settings here.

Custom Rule Engine

If a Default Rule Engine feature set does not cover your use case, you can implement your custom Rule Engine. In that case you will need to:

  1. Implement Rule Engine HTTP API with an HTTP Server Webhook receiver
  2. Expose the server and provide URL to your custom Rule Engine endpoint, using Wabbit Hub Admin Panel

How to configure your custom Rule Engine at the Wabbit Hub Admin Panel: Go to your Hub Admin Panel and click "Rule Engine" then click "Switch to Custom Rule Engine". You will see a form where your custom Rule Engine can be entered. You can also provide optional additional headers that are needed to reach your webhook receiver server, such as Authorization header for security.

Custom Rule Engine needs to expose only one endpoint and will receive WABA Webhook to this endpoint.

As described at the beginning of Rule Engine chapter, there are three events on which Rule Engine Webhook is called. Each event will call your custom Rule Engine with a separate payload exclusively:

  • "incoming_messages" - whenever a new Message arrives from WhatsApp directly to your Inbox,
  • "outgoing_messages" - whenever one of the Inbox Users writes a new Message
  • "tagged_messages" - whenever any existing Message is tagged with a text Tag or advanced metadata ("extra").

See WABA Webhook extension for above fields description.

The result JSON data of custom Rule Engine response has following fields:

Field assignment
Type Array
Required no
Description A list of assignments, if needed.
Example value
[
{
"message_id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60bd",
"user": 42
},
{
"message_id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60be",
"group": 23,
"group_assign_method": "let_group_decide"
}
]
Field assignment.message_id
Type String
Required yes
Description ID of the Message that we want to make assignment on
Example value "d9d2244d-3f31-4229-a7e0-ec38ebcc60bd"
Field assignment.user
Type Integer
Required no
Description ID of the User that has to be assigned to this Message Chat
Example value 42
Field assignment.group
Type Integer
Required no
Description ID of the Group that has to be assigned to this Message Chat
Example value 23
Field assignment.group_assign_method
Type String
Required Required when assignment.group field is returned
Description Which method to use when assigning the Chat to a Group
Possible values "round_robin" (Round Robin) - will instantly assign one of the Group members on a round-robin manner.
"let_group_decide" (Let Group members decide) - will let Group members decide, assigning Group only and leaving the User assignment blank, so that Group members could choose the assignment themself.

Custom Rule Engine response example

Below is an example of response returned by custom Rule Engine implementation:

{
  "assignment": [
        {
            "message_id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60bd",
            "user": 42
        },
        {
            "message_id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60be",
            "group": 23,
            "group_assign_method": "let_group_decide"
        }
    ]
}

Custom Rule Engine implementation example

Below is an example of simple custom Rule Engine writen in Python using AIOHttp library:

#!/usr/bin/env python3

import loguru
import traceback

from aiohttp import web


logger = loguru.logger


routes = web.RouteTableDef()


@routes.post('/webhook')
async def webhook(request: web.Request):

    try:
        response = {
            'assignment': []
        }
        request_data = await request.json()

        if request_data.get('incoming_messages'):
            for message in request_data.get('incoming_messages'):
                # Assign every new message to a bot with User ID = 42
                response['assignment'].append({
                    'message_id': message['id'],
                    'user': 42
                })

        if request_data.get('chat_tagging'):
            tagging = request_data.get('chat_tagging')
            # Assign every Chat rejected by a bot, to a group of Agents
            if tagging['action'] == 'added' and tagging['tag']['name'] == 'Agent needed':
                response['assignment'].append({
                    # Assign a chat to a group
                    'chat_id': tagging['chat'],
                    'group': 23,
                    'group_assign_method': 'let_group_decide'
                })

        if request_data.get('message_tagging'):
            tagging = request_data.get('message_tagging')
            # Remember that Messages can be tagged separately, too
            if tagging['action'] == 'added' and tagging['tag']['name'] == 'Agent needed':
                response['assignment'].append({
                    # Assign a chat to a group, but also indicate which message the assignment is started
                    'message_id': tagging['message'],
                    'group': 23,
                    'group_assign_method': 'let_group_decide'
                })

        return web.json_response(response)

    except Exception as error:
        logger.error(traceback.format_exc())
        return web.json_response({'error': str(error)})


if __name__ == '__main__':
    app = web.Application()
    app.add_routes(routes)
    web.run_app(app)

Here is how an exemplary flow (with participation of above code) could look like. Some details are provided about participating app or bot Users as well.

  1. A new Message is sent from WhatsApp to your Inbox

  2. Wabbit Integration API calls your Rule Engine Webhook with following payload:

    (Irrelevant data hidden for readability)

     {
       "contacts": "...",
       "messages": [ {
         "from": "48123123123",
         "id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60bd",
         "...": "..."
       } ]
     }    
  3. Rule Engine replies with following payload:

    (Assuming the bot User id is 42, for example)

     {
       "assignment": [{
         "message_id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60bd",
         "user": 42
       }]
     }
  4. Wabbit Integration API handles the assignment change and notifies corresponding bot User (user id = 42)

  5. Bot User then receives its own Webhook with following payload:

    (Irrelevant data hidden for readability)

     {
         "assigned_messages": [ {
             "waba_payload": {
                 "from": "48123123123",
                 "id": "ABGGSFEBeRJ_AhD8o8zP9ulNeUPgdK123456",
                 "type": "text",
                 "text": {
                     "body": "Hello"
                 },
                 "...": "..."
             },
             "...": "..."
         } ]
     }    
  6. Bot User then replies to the WhatsApp User using Integration API endpoint post Create Message:

    (Irrelevant data hidden for readability)

     {
       "wa_id": "48123123123",
       "type": "text",
       "text": {
         "body": "Hello! How may I help you?"
       }
     }

    IMPORTANT: It is important to use the same wa_id as in received message (assigned_messages.0.waba_payload.from in the 5. step). By default, bot will be able to reply to assigned Chat only.

    NOTE: A bot might use a template message at this point, showing possible action button answers to the user.

  7. The conversation continues as long as bot can handle the message:

    • Incoming Messages sent from WhatsApp to the bot, arrive as Webhooks with "messages" payload
    • Each response from the bot to the WhatsApp User have to be sent as API post Create Message calls
  8. Eventually, bot cannot handle the conversation no more or human interaction is requested by WhatsApp user explicitly. Then, bot User calls the Integration API to tag the message accordingly using post Create Tagging call.

    When a Message is tagged, then the related Chat is tagged as well and this is what executes the Rule Engine Rule. Still, we recommend to tag Messages instead of Chats, to preserve the history of when the flow has changed. You can choose however to tag the Chat directly instead and this flow will work exactly the same.

  9. Because a new Tagging was made, Integration API calls your custom Rule Engine what to do with following data:

    (Irrelevant data hidden for readability)

     {
       "tagged_messages": [ {
         "message": {
           "id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60be",
           "...": "..."
         },
         "new_tag": {
           "name": "Agent needed",
           "id": 5,
           "extra": {}
         }
       } ]
     }
  10. Rule Engine replies with following payload:

    {
      "assignment": [{
        "message_id": "d9d2244d-3f31-4229-a7e0-ec38ebcc60be",
        "group": 23,
        "group_assign_method": "let_group_decide"
      }]
    }
  11. Integration API assigns then this Message Chat to "Agents" Group (id = 23) and notifies each User in the Group letting them to decide who will be assigned or letting them to continue without any assignment.

    Depending on assignment permission settings, Users may assign themselves to the Chat (by default, they can assign themselves to the Chat they have read access to) or can reply to the Chat their Group is assigned to (by default, they're not allowed to write to Chats they're not directly assigned to)

Contacts

Wabbit Inbox does not keep or manage your contacts. Instead, you can connect your existing contact books or databases, using Contact Providers.

When one or more Contact Providers are successfully connected to your inbox, you will be able to request related contact data from endpoints described here.

listContacts

query Parameters
limit
integer

Number of results to return per page.

This endpoint will return as many results as requested × the number of available Contact Providers. So for example if requesting 2 results per page and there are 3 available Contact Providers, the total number of results can be up to 3 × 2 = 6 results.

Some providers do not support pagination on filtering (e.g. Google People API for personal contacts - G Suite is not the case). In such cases, this parameter will not be respected and all filtered results are returned.

search
string

Filter Contacts by string query.

Each available Contact Provider will perform search in their data. Details on where search is performed varies between contact providers, but it often means searching inside contact name, contact phone number and sometimes inside all fields provided by related contact provider.

Searching Contact Providers is expensive, so when implementing this functionality on the frontend, make sure the user really finished typing the search query before calling this endpoint.

Responses

Response Schema: application/json
count
integer

Total number of Contacts in all Contact Providers, filtered by specified query (if provided). Some Contact Providers will not provide this value, then the returned value will be null.

If at least one provider returned count equal to null, then the resulting value will be null.

next
string <uri> Nullable

Different Contact Providers work differently. Some of them will provide to you pagination with explicit query params like limit, offset or page number. Other will provide pagination token. This URL parameter unifies pagination methods. When you specify your desired page size with limit parameter of this endpoint, this URL will already have all params needed that are sent to related Contact Providers.

In other words, it's not possible to set the page number or offset explicitly in this request. That's why this request params are lacking such variables. You need to always start with zero page, by calling this endpoint with desired limit param and then call the URL returned in next field to get every next page.

Array of objects (ContactProviderResult)

Response samples

Content type
application/json
{
  • "count": 123,
  • "results": [
    • {
      • "name": "string",
      • "initials": "string",
      • "avatar": "http://example.com",
      • "large_avatar": "http://example.com",
      • "phone_numbers": [
        • {
          }
        ],
      • "email_addresses": [
        • {
          }
        ],
      • "urls": [],
      • "contact_provider": {
        • "type": "google",
        • "name": "string",
        • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
      }
    ]
}

resolveContact

Resolves Contact details by querying all Contact Providers connected to your inbox. This endpoint communicates with each provider directly, so it provides up-to-date data and isn't very efficient. You should try to use this endpoint as little as possible, for example:

  • when a list of Persons is displayed and you want to update the list of names with Contact Provider data

  • when a detailed view of one Person is displayed

path Parameters
wa_id
required
string

A unique value identifying this contact.

Responses

Response Schema: application/json
object

Person related to this contact. Can be null if this person wasn't yet contacted via your inbox or related Person data was removed from your inbox.

required
Array of objects

Results returned from Contact Providers connected to your account.

Each object is a single result, but it is possible that one Contact Provider will return more than one result for a given wa_id.

If no Contact Provider is currently available, this field is an empty array.

Response samples

Content type
application/json
{
  • "person": {
    • "wa_id": "string",
    • "waba_payload": {
      • "profile": {
        • "name": "string"
        },
      • "wa_id": "string"
      },
    • "initials": "string",
    • "last_message_timestamp": 0
    },
  • "contact_provider_results": [
    • {
      • "name": "string",
      • "initials": "string",
      • "avatar": "http://example.com",
      • "large_avatar": "http://example.com",
      • "phone_numbers": [
        • {
          }
        ],
      • "email_addresses": [
        • {
          }
        ],
      • "urls": [],
      • "contact_provider": {
        • "type": "google",
        • "name": "string",
        • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
      }
    ]
}

verifyContacts

WABA This endpoint works the same as /v1/contacts WhatsApp Business API endpoint.

Verifies given contacts, by calling WhatsApp Business API directly.

Request Body schema:
blocking
string
Default: "no_wait"
Enum: "no_wait" "wait"

Whether the API request should wait for processing to complete or not before returning a response. For more information, read the Blocking section of WhatsApp Business API documentation.

contacts
required
Array of strings

Array of phone numbers that you are validating.

The numbers can be in any standard telephone number format. The recommended format for contact phone numbers is with a plus sign (+) and the country code. For more information, see the Phone Number Formats section of WhatsApp Business API documentation.

force_check
boolean
Default: false

Whether to check the contacts cache or not. Contact information is normally cached for 7 days. By setting the force_check parameter to true, the cache will be bypassed ensuring a check is performed.

Responses

Response Schema: application/json
Array of objects

Request samples

Content type
{
  • "blocking": "no_wait",
  • "contacts": [
    • "string"
    ],
  • "force_check": false
}

Response samples

Content type
application/json
{
  • "contacts": [
    • {
      • "wa_id": "16315551000",
      • "input": "16315551000",
      • "status": "valid"
      },
    • {
      • "wa_id": "16315551001",
      • "input": "+1 631 555 1001",
      • "status": "processing"
      },
    • {
      • "input": "6315551002",
      • "status": "invalid"
      },
    • {
      • "input": "+163155588",
      • "status": "failed"
      }
    ]
}

Persons

Chat participants who contacted your inbox via WhatsApp

retrievePerson

path Parameters
wa_id
required
string

Responses

Response Schema: application/json
wa_id
required
string <= 100 characters
required
object
initials
required
string

Contact user name initials used for display when avatar image is missing

last_message_timestamp
integer Nullable

POSIX timestamp of last message that was sent by this contact. This allows to determine the customer care 24h window. Any non-template message can only be delivered in the 24 hours after last time customer sent a message to your business. Read more at WhatsApp Business API docs Messages Cut-off Control.

Response samples

Content type
application/json
{
  • "wa_id": "string",
  • "waba_payload": {
    • "profile": {
      • "name": "string"
      },
    • "wa_id": "string"
    },
  • "initials": "string",
  • "last_message_timestamp": 0
}

listPersons

query Parameters
limit
integer
offset
integer
search
string

Filter Persons by string query - search for Persons containing specified text phrase.

The API will search in following places:

  • waba_payload.wa_id

  • waba_payload.profile.name

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (Person)

Response samples

Content type
application/json
{}

Tags

A Tag is an object that is used when tagging Chats and Messages.

A MessageTagging is a relationship object defining which Messages are tagged with which Tags.

A ChatTagging is a relationship object defining which Chats are tagged with which Tags.

A MessageTaggingEvent is a historical entry object defining which Messages were tagged with which Tags, by which User and when.

A ChatTaggingEvent is a historical entry object defining which Chats were tagged with which Tags, by which User and when.

retrieveMessageTagging

path Parameters
id
required
string

A unique integer value identifying this message tagging.

Responses

Response Schema: application/json
id
integer

This tagging relation ID. Used when deleting a tagging for example.

tag
required
integer

ID of related Tag

message
required
string

Message ID string known from WABA payload

extra
object Nullable

Optional additional data. Should not be used on front-end apps. Use only to pass extra data between systems / apps / bots, when Message is tagged.

Response samples

Content type
application/json
{
  • "id": 0,
  • "tag": 0,
  • "message": "string",
  • "extra": { }
}

destroyMessageTagging

tags: - Tags

path Parameters
id
required
string

A unique integer value identifying this message tagging.

Responses

listMessageTaggingEvents

List all Message tagging events for selected Chat or Message

query Parameters
wa_id
string

WhatsApp ID of related Chat

message_id
string

Message ID

since_time
integer

POSIX timestamp. Returns only events that are at the same timestamp or newer than specified since_time. Note that, as opposed to before_time param, this param returns messages where timestamp is equal to the given value.

This should be used when implementing scroll of the event view from oldest to newest.

before_time
integer

POSIX timestamp. Returns only events that are older than specified before_time.

This should be used when implementing scroll of the event view from newest to oldest.

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (MessageTaggingEvent)

Response samples

Content type
application/json
{
  • "count": 123,
  • "results": [
    • {
      • "timestamp": 0,
      • "action": "added",
      • "tag": {
        • "id": 0,
        • "name": "string",
        • "web_inbox_color": "string"
        },
      • "message": "string",
      • "extra": { },
      • "done_by": {
        • "url": "string",
        • "id": 0,
        • "username": "string",
        • "first_name": "string",
        • "last_name": "string",
        • "email": "user@example.com",
        • "profile": {
          },
        • "groups": [
          ],
        • "permissions": {
          }
        }
      }
    ]
}

retrieveChatTagging

path Parameters
id
required
string

A unique integer value identifying this chat tagging.

Responses

Response Schema: application/json
id
integer
tag
required
integer

ID of related Tag

chat
required
string

WhatsApp ID of related WhatsApp User the Chat is made with

extra
object Nullable

Optional additional data. Should not be used on front-end apps. Use only to pass extra data between systems / apps / bots, when Chat is tagged.

Response samples

Content type
application/json
{
  • "id": 0,
  • "tag": 0,
  • "chat": "string",
  • "extra": { }
}

destroyChatTagging

tags: - Tags

path Parameters
id
required
string

A unique integer value identifying this chat tagging.

Responses

listChatTaggingEvents

List all Chat tagging events for selected Chat

query Parameters
wa_id
string

WhatsApp ID of related Chat

since_time
integer

POSIX timestamp. Returns only events that are at the same timestamp or newer than specified since_time. Note that, as opposed to before_time param, this param returns messages where timestamp is equal to the given value.

This should be used when implementing scroll of the event view from oldest to newest.

before_time
integer

POSIX timestamp. Returns only events that are older than specified before_time.

This should be used when implementing scroll of the event view from newest to oldest.

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (ChatTaggingEvent)

Response samples

Content type
application/json
{
  • "count": 123,
  • "results": [
    • {
      • "timestamp": 0,
      • "action": "added",
      • "tag": {
        • "id": 0,
        • "name": "string",
        • "web_inbox_color": "string"
        },
      • "chat": "string",
      • "extra": { },
      • "done_by": {
        • "url": "string",
        • "id": 0,
        • "username": "string",
        • "first_name": "string",
        • "last_name": "string",
        • "email": "user@example.com",
        • "profile": {
          },
        • "groups": [
          ],
        • "permissions": {
          }
        }
      }
    ]
}

listTags

query Parameters
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (Tag)

Response samples

Content type
application/json
{}

createTag

Create a new Tag that can be later used to tag Messages or Chats

Request Body schema:
name
required
string <= 1000 characters
web_inbox_color
string <= 1000 characters Nullable

A Web App related setting - which color to show on the Web App frontend

Responses

Request samples

Content type
{
  • "name": "string",
  • "web_inbox_color": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "web_inbox_color": "string"
}

createMessageTagging

Assign a Tag to selected Message. Note that by tagging a Message, corresponding Chat is tagged automatically with the same tag.

You cannot create the same Message + Tag Tagging pair twice, however you can delete and create the same pair again.

Request Body schema:
tag
required
integer

ID of related Tag

message
required
string

Message ID string known from WABA payload

extra
object Nullable

Optional additional data. Should not be used on front-end apps. Use only to pass extra data between systems / apps / bots, when Message is tagged.

Responses

Request samples

Content type
{
  • "tag": 0,
  • "message": "string",
  • "extra": { }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "tag": 0,
  • "message": "string",
  • "extra": { }
}

createChatTagging

Assign a Tag to selected Chat.

You cannot create the same Chat + Tag Tagging pair twice, however you can delete and create the same pair again.

Request Body schema:
tag
required
integer

ID of related Tag

chat
required
string

WhatsApp ID of related WhatsApp User the Chat is made with

extra
object Nullable

Optional additional data. Should not be used on front-end apps. Use only to pass extra data between systems / apps / bots, when Chat is tagged.

Responses

Request samples

Content type
{
  • "tag": 0,
  • "chat": "string",
  • "extra": { }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "tag": 0,
  • "chat": "string",
  • "extra": { }
}

destroyTag

tags: - Tags

path Parameters
id
required
string

Responses

Webhooks

These API endpoints allow you to manage Webhooks.

To learn more about Webhooks' payload and when to expect them see Integration > WABA Webhook extension chapter

listWabaWebhooks

Webhook sent by WhatsApp Business API to your endpoint(s)

Only admin Users can see a list of all Users WABA Webhooks. Other Users receive a list of one element of their own WABA Webhook (if configured).

This resource describes configuration of webhook sent from WhatsApp Business API / WABA Stack to one of your apps (or systems). WhatsApp Business API itself allows you to integrate only one webhook. With our API you can set up multiple per-user webhooks.

See Integration chapter to learn more about per-user webhooks.

query Parameters
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (WabaWebhook)

Response samples

Content type
application/json
{}

createWabaWebhook

Create WABA Webhook for this user (currently logged in user)

You can create only one WABA Webhook per API User.

After this webhook is created, WABA webhooks are propagated to your URL starting from next webhook.

See WABA Webhook section to learn more how propagation works.

Request Body schema:
url
required
string <uri> ^(?:[a-z0-9.+-]*)://(?:[^\s:@/]+(?::[^\s:@/]*...

Remember to use https:// URLs for your webhooks!

Note: You can validate Webhook events by specifying a shared secret as a query parameter when you set the Webhook URL. Example: https://url?auth={shared_secret}.

Responses

Request samples

Content type

Response samples

Content type
application/json
{
  • "id": 0,
  • "user": {
    • "id": 0,
    • "username": "string",
    • "url": "string"
    },
}

retrieveWabaWebhook

path Parameters
id
required
string

Responses

Response Schema: application/json
id
integer
object
url
required
string <uri> ^(?:[a-z0-9.+-]*)://(?:[^\s:@/]+(?::[^\s:@/]*...

Remember to use https:// URLs for your webhooks!

Note: You can validate Webhook events by specifying a shared secret as a query parameter when you set the Webhook URL. Example: https://url?auth={shared_secret}.

Response samples

Content type
application/json
{
  • "id": 0,
  • "user": {
    • "id": 0,
    • "username": "string",
    • "url": "string"
    },
}

updateWabaWebhook

path Parameters
id
required
string
Request Body schema:
url
required
string <uri> ^(?:[a-z0-9.+-]*)://(?:[^\s:@/]+(?::[^\s:@/]*...

Remember to use https:// URLs for your webhooks!

Note: You can validate Webhook events by specifying a shared secret as a query parameter when you set the Webhook URL. Example: https://url?auth={shared_secret}.

Responses

Response Schema: application/json
id
integer
object
url
required
string <uri> ^(?:[a-z0-9.+-]*)://(?:[^\s:@/]+(?::[^\s:@/]*...

Remember to use https:// URLs for your webhooks!

Note: You can validate Webhook events by specifying a shared secret as a query parameter when you set the Webhook URL. Example: https://url?auth={shared_secret}.

Request samples

Content type

Response samples

Content type
application/json
{
  • "id": 0,
  • "user": {
    • "id": 0,
    • "username": "string",
    • "url": "string"
    },
}

deleteWabaWebhook

Deletes WABA Webhook permanently

path Parameters
id
required
string

Responses

Messages

listMessages

A wrapper of messages object of Inbound Notifications from WhatsApp Business API (WABA Stack).

This object field waba_payload contains exactly the same data as specified in WhatsApp Business API.

This endpoint is useful for loading messages into a view. Example use cases:

  • Message view is loaded for the first time
  • Contact message history is loaded or is scrolled

To get the number of new messages for all contacts, see chats endpoint.

Messages are ordered from newest to oldest.

You can use limit and offset query parameters to access each page, but it is often advised to use before_time instead of offset.

For example, if you only need to get most recent 20 messages, you will use:

/api/v1/messages/48123123123/?limit=20

But if you need to read the history of 20 messages before, you should use before_time equal to the timestamp of the last (20th) message you got before:

/api/v1/messages/48123123123/?limit=20&before_time=1234567890

As a result, you will get up to 20 messages that were sent before previous 20 messages.

Using before_time instead of offset is advised because it is possible you will get new messages when you browse your paginated history of messages. Since messages are ordered from newest to oldest, offset based pagination is changing each time you receive a new message from a contact. Using before_time solves this problem.

query Parameters
wa_id
string

WhatsApp id of related contact

limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

since_time
integer

POSIX timestamp. Returns only messages that are at the same timestamp or newer than specified since_time.

This should be used when implementing scroll of the messages from oldest to newest.

before_time
integer

POSIX timestamp. Returns only messages that are older than specified before_time. This parameter makes it easy to just pass the timestamp of the last message you have and receive only messages older than related message.

This should be used when implementing scroll of the messages from newest to oldest.

mark_as_received
integer

Mark all returned messages as received by you (logged in user). You need to use either this param or POST to /mark_as_received/ endpoint to mark messages as received. Marking messages as received by you is needed to generate a proper list of new messages. (You can check how many unread messages there are for each contact with /chats/ endpoint.) It is required to use one or the other when you implement any kind of indication of new/unread messages or when you simply forward messages to your system in batches and would like to receive only fresh messages on each iteration.

search
string

Filter Messages by string query - search for messages containing specified text phrase.

The API will search in following places:

* `text.body` field of `waba_payload` JSON

* `{media_type}.caption` or `{media_type}.filename` of media type message fields:
    `image`, `document`, `audio`, `video` ,`voice`, `sticker`"

* `name` field of each Tag in `tags` field of each Message
assigned_to_me
boolean

Filter only Messages of Chats assigned to currently logged in User. Skip this param or leave default false to display all messages User has access to.

assigned_group
integer

Filter only Messages of Chats assigned to specified Group. Skip this param to display all messages currently logged in User has access to. Param value is an integer identifier of the Group. Only Groups the User is member of can be used.

Responses

Response Schema: application/json
count
integer
next
string Nullable
previous
string Nullable
Array of objects (RetrieveMessage)

Response samples

Content type
application/json
Example
{
  • "count": 1,
  • "next": null,
  • "previous": null,
  • "results": [
    • {
      • "waba_payload": {
        • "preview_url": false,
        • "recipient_type": "individual",
        • "to": "48123123123",
        • "type": "text",
        • "text": {
          },
        • "id": "gBGGSFEBeRJ_AgnJkfda1iRwQteM",
        • "timestamp": "1611319126"
        },
      • "customer_wa_id": "48123123123",
      • "from_us": false,
      • "received": true,
      • "sender": {}
      }
    ]
}

createMessage

Create a new message

This object contains selected data that is following specification of WhatsApp Business API.

The type field determines the type of message. Choosing one of possible types makes related field required. For example, choosing "type": "text" makes field text required.

Request Body schema: application/json
wa_id
required
string

WhatsApp ID of the message recipient

type
required
string
Enum: "text" "image" "contacts" "document" "hsm" "location" "sticker" "template"
object
object
object
object
template
contacts
location

Responses

Response Schema: application/json
waba_response
object

Request samples

Content type
application/json
Example
{
  • "type": "text",
  • "text": {
    • "body": "Hello!"
    }
}

Response samples

Content type
application/json
{ }

createReceivedMessageMark

Create a new mark, marking messages as received.

Every new message will be provided via /chats/ endpoint. In order to no longer receive these messages via above endpoint, you need to mark them as received.

You can parse /messages/ endpoint object field received to determine if a given message still needs to be marked as received. By POSTing data to this endpoint, you create (or update) a mark of timestamp in relation to a conversation with a contact of given customer_wa_id.

It is recommended to

  • use WABA Webhooks
  • or to POST to this endpoint whenever you receive a batch of messages using /messages/ endpoint and you confirmed the message was received by the user.

Forwarding messages to your system

If you develop some kind of integration of data between systems or simply bridge these messages to other systems, received message mark is useful for determining which Chats have new messages. By using /chats/ endpoint you can quickly determine which contacts have new, unreceived messages. But to keep this endpoint up to date, you need to create received message marks.

Instant mark

Messages propagated to a User via WABA Webhook successfully (200 OK status code) are automatically marked as received by related User.

It is also possible to mark messages as received "instantly" when polling them via our API directly. In such case you should use mark_as_received parameter of /messages/ endpoint.

If you use mentioned mark_as_received parameter or you configured a WABA Webhook, usage of the /mark_as_received/ endpoint described here is no longer needed.

Request Body schema:
timestamp
required
integer
customer_wa_id
required
string

Responses

Response Schema: application/json
object

Request samples

Content type
{
  • "timestamp": 0,
  • "customer_wa_id": "string"
}

Response samples

Content type
application/json
{ }

Chats

listChats

Get existing chats and the number of new messages in each chat.

This endpoint is similar to /persons/ endpoint

  • here also contacts are listed, but only these contacts for which conversation already exists.

Chats are sorted by last_message_timestamp, newest to oldest.

To mark these messages as received, first store wa_id (WhatsApp ID) field value of this endpoint. Then use messages endpoint to read messages for related contact and store the message id. After making sure the user has received the message on the frontend, check the timestamp of the most recent message received and use it with /mark_as_received/ endpoint to actually mark it as received.

Marking messages as received is important to prevent duplicate notifications.

Response is paginated. Use limit and offset query parameters to access each page. Query parameter limit default value is 100. JSON response body field count tells the total number of elements available on all pages.

query Parameters
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

search
string

Filter Chats by string query - search for chats containing specified text phrase. The API will search in following places:

  • contact.waba_payload.profile.name and contact.waba_payload.wa_id of each Chat
  • name field of each Tag in tags of each Chat
assigned_to_me
boolean

Filter only Chats assigned to currently logged in User. Skip this param or leave default false to display all messages User has access to.

assigned_group
integer

Filter only Chats assigned to specified Group. Skip this param to display all messages currently logged in User has access to. Param value is an integer identifier of the Group. Only Groups the User is member of can be used.

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (Chat)

Response samples

Content type
application/json
{
  • "count": 123,
  • "results": [
    • {
      • "contact": {
        • "wa_id": "string",
        • "waba_payload": {
          },
        • "initials": "string",
        • "last_message_timestamp": 0
        },
      • "new_messages": 0,
      • "wa_id": "string",
      • "last_message": {
        • "id": "string",
        • "waba_payload": { },
        • "waba_statuses": {
          },
        • "contact": {
          },
        • "from_us": true,
        • "received": false,
        • "sender": {
          },
        • "context": { },
        • "customer_wa_id": "string",
        • "tags": [
          ]
        },
      • "assigned_to_user": {
        • "url": "string",
        • "id": 0,
        • "username": "string",
        • "first_name": "string",
        • "last_name": "string",
        • "email": "user@example.com",
        • "profile": {
          },
        • "groups": [
          ],
        • "permissions": {
          }
        },
      • "assigned_group": {
        • "id": 0,
        • "name": "string"
        },
      • "tags": [
        • {
          }
        ]
      }
    ]
}

retrieveChat

path Parameters
wa_id
required
string

Responses

Response Schema: application/json
required
object

Who are we talking to

new_messages
required
integer

The number of messages not received by currently authenticated user

wa_id
required
string

Deprecated

required
object
required
object
required
object
required
Array of objects

Response samples

Content type
application/json
{
  • "contact": {
    • "wa_id": "string",
    • "waba_payload": {
      • "profile": {
        • "name": "string"
        },
      • "wa_id": "string"
      },
    • "initials": "string",
    • "last_message_timestamp": 0
    },
  • "new_messages": 0,
  • "wa_id": "string",
  • "last_message": {
    • "id": "string",
    • "waba_payload": { },
    • "waba_statuses": {
      • "sent": 0,
      • "delivered": 0,
      • "read": 0
      },
    • "contact": {
      • "wa_id": "string",
      • "waba_payload": {
        • "profile": {
          },
        • "wa_id": "string"
        },
      • "initials": "string",
      • "last_message_timestamp": 0
      },
    • "from_us": true,
    • "received": false,
    • "sender": {
      • "url": "string",
      • "id": 0,
      • "username": "string",
      • "first_name": "string",
      • "last_name": "string",
      • "email": "user@example.com",
      • "profile": {
        • "role": "user"
        },
      • "groups": [
        • {
          }
        ],
      • "permissions": {
        • "can_use_tags": true,
        • "can_read_chats": "all",
        • "can_write_to_chats": "all"
        }
      },
    • "context": { },
    • "customer_wa_id": "string",
    • "tags": [
      • {
        • "name": "string",
        • "web_inbox_color": "string",
        • "tagging_id": 0,
        • "id": 0,
        • "extra": { }
        }
      ]
    },
  • "assigned_to_user": {
    • "url": "string",
    • "id": 0,
    • "username": "string",
    • "first_name": "string",
    • "last_name": "string",
    • "email": "user@example.com",
    • "profile": {
      • "role": "user"
      },
    • "groups": [
      • {
        • "id": 0,
        • "name": "string"
        }
      ],
    • "permissions": {
      • "can_use_tags": true,
      • "can_read_chats": "all",
      • "can_write_to_chats": "all"
      }
    },
  • "assigned_group": {
    • "id": 0,
    • "name": "string"
    },
  • "tags": [
    • {
      • "name": "string",
      • "web_inbox_color": "string",
      • "tagging_id": 0,
      • "id": 0,
      • "extra": { }
      }
    ]
}

Assignment

retrieveChatAssignment

path Parameters
wa_id
required
string

A unique value identifying this contact.

Responses

Response Schema: application/json
wa_id
required
string <= 100 characters
assigned_to_user
integer Nullable

ID of the User this Chat is assigned to

assigned_group
integer Nullable

ID of the Group assigned

Response samples

Content type
application/json
{
  • "wa_id": "string",
  • "assigned_to_user": 0,
  • "assigned_group": 0
}

updateChatAssignment

Assign a Chat to yourself or any User or Group

You can only assign a Chat to a User when nobody is assigned or if you are in the Admin group.

You can remove Chat assignment by passing null value, but you can only remove Chat assignment if the Chat is assigned to you or you are in the Admin group.

path Parameters
wa_id
required
string

A unique value identifying this contact.

Request Body schema:
wa_id
required
string <= 100 characters
assigned_to_user
integer Nullable

ID of the User this Chat is assigned to

assigned_group
integer Nullable

ID of the Group assigned

Responses

Response Schema: application/json
wa_id
required
string <= 100 characters
assigned_to_user
integer Nullable

ID of the User this Chat is assigned to

assigned_group
integer Nullable

ID of the Group assigned

Request samples

Content type
{
  • "wa_id": "string",
  • "assigned_to_user": 0,
  • "assigned_group": 0
}

Response samples

Content type
application/json
{
  • "wa_id": "string",
  • "assigned_to_user": 0,
  • "assigned_group": 0
}

partialUpdateChatAssignment

Assign a Chat to yourself or any User or Group

Partial update allows you to change the User only or Group only, by using corresponding field only.

You can only assign a Chat to a User when nobody is assigned or if you are in the Admin group.

You can remove Chat assignment by passing null value, but you can only remove Chat assignment if the Chat is assigned to you or you are in the Admin group.

path Parameters
wa_id
required
string

A unique value identifying this contact.

Request Body schema:
wa_id
required
string <= 100 characters
assigned_to_user
integer Nullable

ID of the User this Chat is assigned to

assigned_group
integer Nullable

ID of the Group assigned

Responses

Response Schema: application/json
wa_id
required
string <= 100 characters
assigned_to_user
integer Nullable

ID of the User this Chat is assigned to

assigned_group
integer Nullable

ID of the Group assigned

Request samples

Content type
{
  • "wa_id": "string",
  • "assigned_to_user": 0,
  • "assigned_group": 0
}

Response samples

Content type
application/json
{
  • "wa_id": "string",
  • "assigned_to_user": 0,
  • "assigned_group": 0
}

listChatAssignmentEvents

List all Chat assignment events for selected Chat

query Parameters
wa_id
string

WhatsApp ID of related Chat

since_time
integer

POSIX timestamp. Returns only events that are at the same timestamp or newer than specified since_time. Note that, as opposed to before_time param, this param returns messages where timestamp is equal to the given value.

This should be used when implementing scroll of the event view from oldest to newest.

before_time
integer

POSIX timestamp. Returns only events that are older than specified before_time.

This should be used when implementing scroll of the event view from newest to oldest.

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (ChatAssignmentEvent)

Response samples

Content type
application/json
{
  • "count": 123,
  • "results": [
    • {
      • "timestamp": 0,
      • "wa_id": "string",
      • "assigned_to_user_set": {
        • "url": "string",
        • "id": 0,
        • "username": "string",
        • "first_name": "string",
        • "last_name": "string",
        • "email": "user@example.com",
        • "profile": {
          },
        • "groups": [
          ],
        • "permissions": {
          }
        },
      • "assigned_to_user_was_cleared": true,
      • "assigned_group_set": {
        • "id": 0,
        • "name": "string"
        },
      • "assigned_group_was_cleared": true,
      • "done_by": {
        • "url": "string",
        • "id": 0,
        • "username": "string",
        • "first_name": "string",
        • "last_name": "string",
        • "email": "user@example.com",
        • "profile": {
          },
        • "groups": [
          ],
        • "permissions": {
          }
        }
      }
    ]
}

Saved Responses

listSavedResponses

query Parameters
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (SavedResponse)

Response samples

Content type
application/json
{}

createSavedResponse

Request Body schema:
text
required
string

Responses

Request samples

Content type
{
  • "text": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "text": "string",
  • "created_by": "string",
  • "timestamp": 0
}

deleteSavedResponse

operationId: deleteSavedResponse tags: - Saved Responses

path Parameters
id
required
string

A unique integer value identifying this saved response.

Responses

Templates

listTemplates

List all your message templates.

query Parameters
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (Template)

Response samples

Content type
application/json
{}

createTemplate

Create a new message template.

Editing templates is not supported. To update one of your templates, please delete current template and then create a new one.

Entire body schema follows schema as explained in WhatsApp Business API Message Templates documentation.

In above link, you can find more information about parameters, components, and buttons. There is also a list of all supported languages here.

Request Body schema:
name
required
string

The name of the message template.

category
required
string

The type of message template. Values: ACCOUNT_UPDATE, PAYMENT_UPDATE, PERSONAL_FINANCE_UPDATE, SHIPPING_UPDATE, RESERVATION_UPDATE, ISSUE_RESOLUTION, APPOINTMENT_UPDATE, TRANSPORTATION_UPDATE, TICKET_UPDATE, ALERT_UPDATE, AUTO_REPLY

language
required
string

The language of message template, e.g. en_US

components
required
Array of objects

The list of definitions of parts of message template. See WhatsApp Business API Documentation.

Responses

Request samples

Content type
{
  • "name": "string",
  • "category": "string",
  • "language": "string",
  • "components": [
    • { }
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "category": "string",
  • "language": "string",
  • "components": [
    • { }
    ],
  • "namespace": "string",
  • "rejected_reason": "string",
  • "status": "string"
}

destroyTemplate

Delete a given message template

path Parameters
name
required
string

Responses

Media files

retrieveMediaFile

Retrieve binary raw media file

Used in media messages and for display.

path Parameters
id
required
string

A UUID string identifying this media file.

Responses

Response Schema:
binary

createMediaFile

Create a new media file

Use this endpoint to upload a new media file before you enter it into a new message as an attachment.

Request Body schema:
file_encoded
required
string <binary>

Binary file

encoded in base64 encoding of binary data.

JavaScript multipart/form-data Example:

let file = document.getElementById('my_file').files[0];
const file = document.querySelector("input[type=file]").files[0];

let data = new FormData();
data.append('file_encoded', file);

fetch('/api/v1/media/', {
'method': 'POST',
'headers': {
  'X-CSRFToken': '{{ csrf_token }}',
},
'body': data
}).then(response => {
  return response.json();
}).then(data => {
  console.log(data.file);
}).catch((error) => {
  console.error('Error:', error);
});

Above POST request will produce a valid binary file upload HTTP request similar to:

-----------------------------332889473834598984683101881237
Content-Disposition: form-data; name="file_encoded"; filename="img.jpg"
Content-Type: image/jpeg

<binary data here>

After API will return with specified JSON data, line console.log(data.file); will print a direct URL to uploaded media file.

Responses

Request samples

Content type
{
  • "file_encoded": "string"
}

Response samples

Content type
application/json
{
  • "file": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Users

listUsers

query Parameters
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (User)

Response samples

Content type
application/json
{}

createNewUser

Creates a new User. Only admin Users can create new Users.

IMPORTANT: Heads up! This request response returns an activation_url field, which is returned this way only once!

When you create a new User using this API, you need to call returned activation_url in order to activate newly created account.

Activating app Users

If you created a new User with role "app", calling the activation_url will result with a JSON response equal to Token Authorization request response, for example:

{"token": "8aeb44f5a318542d32bb13019d68198467ee21f0"}

You can then use this token with no need to set any password for this User.

Note that for "app" users, the activation code is no longer valid after the token is returned!

Activating regular and admin Users

When creating regular users, you might want to set password first and then activate the User afterwards. Use /users/{id}/password/change/ to set a password for this new User and then activate it.

If you integrate our API to an external system, you can integrate this URL so that users activate their accounts themselves either via email or any other solution you're using.

After activation URL is called, the account is ready to be used.

Request Body schema:
username
required
string

Username that is used in combination with password during login.

Only alphanumeric characters are allowed (A-Z, a-z, 0-9).

first_name
string <= 150 characters
last_name
string <= 150 characters
email
string <email>
object

Optional field used to create app users and additional admin users

Responses

Request samples

Content type
{
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "profile": {
    • "role": "user"
    }
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "activation_url": "http://example.com",
  • "id": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "profile": {
    • "role": "user"
    }
}

retrieveCurrentUser

Get object of currently logged in User

Responses

Response Schema: application/json
url
string
id
integer
username
required
string

Username that is used in combination with password during login.

Only alphanumeric characters are allowed (A-Z, a-z, 0-9).

first_name
string
last_name
string
email
required
string <email>

E-mail address of this new user.

object

Optional field used to create app users and additional admin users

required
Array of objects
required
object

Response samples

Content type
application/json
{
  • "url": "string",
  • "id": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "profile": {
    • "role": "user"
    },
  • "groups": [
    • {
      • "id": 0,
      • "name": "string"
      }
    ],
  • "permissions": {
    • "can_use_tags": true,
    • "can_read_chats": "all",
    • "can_write_to_chats": "all"
    }
}

retrieveUser

path Parameters
id
required
string

Responses

Response Schema: application/json
url
string
id
integer
username
required
string

Username that is used in combination with password during login.

Only alphanumeric characters are allowed (A-Z, a-z, 0-9).

first_name
string
last_name
string
email
required
string <email>

E-mail address of this new user.

object

Optional field used to create app users and additional admin users

required
Array of objects
required
object

Response samples

Content type
application/json
{
  • "url": "string",
  • "id": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "profile": {
    • "role": "user"
    },
  • "groups": [
    • {
      • "id": 0,
      • "name": "string"
      }
    ],
  • "permissions": {
    • "can_use_tags": true,
    • "can_read_chats": "all",
    • "can_write_to_chats": "all"
    }
}

updateUser

Update user data - all fields are required. Only admin Users and related User can update this data.

path Parameters
id
required
string
Request Body schema:
username
required
string

Username that is used in combination with password during login.

Only alphanumeric characters are allowed (A-Z, a-z, 0-9).

email
required
string <email>

E-mail address of this new user.

object

Optional field used to create app users and additional admin users

required
Array of objects
required
object

Responses

Response Schema: application/json
url
string
id
integer
username
required
string

Username that is used in combination with password during login.

Only alphanumeric characters are allowed (A-Z, a-z, 0-9).

first_name
string
last_name
string
email
required
string <email>

E-mail address of this new user.

object

Optional field used to create app users and additional admin users

required
Array of objects
required
object

Request samples

Content type
{
  • "username": "string",
  • "email": "user@example.com",
  • "profile": {
    • "role": "user"
    },
  • "groups": [
    • {
      • "id": 0,
      • "name": "string"
      }
    ],
  • "permissions": {
    • "can_use_tags": true,
    • "can_read_chats": "all",
    • "can_write_to_chats": "all"
    }
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "id": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "profile": {
    • "role": "user"
    },
  • "groups": [
    • {
      • "id": 0,
      • "name": "string"
      }
    ],
  • "permissions": {
    • "can_use_tags": true,
    • "can_read_chats": "all",
    • "can_write_to_chats": "all"
    }
}

partialUpdateUser

Partially update user data - all fields are optional. Only admin Users and related User can update this data.

path Parameters
id
required
string
Request Body schema:
username
required
string

Username that is used in combination with password during login.

Only alphanumeric characters are allowed (A-Z, a-z, 0-9).

email
required
string <email>

E-mail address of this new user.

object

Optional field used to create app users and additional admin users

required
Array of objects
required
object

Responses

Response Schema: application/json
url
string
id
integer
username
required
string

Username that is used in combination with password during login.

Only alphanumeric characters are allowed (A-Z, a-z, 0-9).

first_name
string
last_name
string
email
required
string <email>

E-mail address of this new user.

object

Optional field used to create app users and additional admin users

required
Array of objects
required
object

Request samples

Content type
{
  • "username": "string",
  • "email": "user@example.com",
  • "profile": {
    • "role": "user"
    },
  • "groups": [
    • {
      • "id": 0,
      • "name": "string"
      }
    ],
  • "permissions": {
    • "can_use_tags": true,
    • "can_read_chats": "all",
    • "can_write_to_chats": "all"
    }
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "id": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "profile": {
    • "role": "user"
    },
  • "groups": [
    • {
      • "id": 0,
      • "name": "string"
      }
    ],
  • "permissions": {
    • "can_use_tags": true,
    • "can_read_chats": "all",
    • "can_write_to_chats": "all"
    }
}

changeMyPassword

Change your password (currently logged in User)

Request Body schema:
current_password
required
string

Provide current password for security

new_password
required
string

Provide a new password that will be set to your account now

Responses

Response Schema: application/json

Request samples

Content type
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
{ }

changeUserPassword

Change password of somebody else (only available for admins)

path Parameters
id
required
string
Request Body schema:
password
required
string

Responses

Response Schema: application/json

Request samples

Content type
{
  • "password": "string"
}

Response samples

Content type
application/json
{ }

Groups

listGroups

query Parameters
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

Response Schema: application/json
count
integer
next
string <uri> Nullable
previous
string <uri> Nullable
Array of objects (Group)

Response samples

Content type
application/json
{}

retrieveGroup

path Parameters
id
required
string

A unique integer value identifying this user group.

Responses

Response Schema: application/json
id
integer
name
required
string <= 1000 characters

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string"
}

Business Profile

retrieveBusinessProfileSettings

Responses

Response Schema: application/json
address
required
string
description
required
string
email
required
string <email>
vertical
required
string
Enum: "Automotive" "Beauty, Spa and Salon" "Clothing and Apparel" "Education" "Entertainment" "Event Planning and Service" "Finance and Banking" "Food and Grocery" "Public Service" "Hotel and Lodging" "Medical and Health" "Non-profit" "Professional Services" "Shopping and Retail" "Travel and Transportation" "Restaurant" "Other"
websites
Array of any

Response samples

Content type
application/json
{
  • "address": "string",
  • "description": "string",
  • "email": "user@example.com",
  • "vertical": "Automotive",
  • "websites": [
    • null
    ]
}

partialUpdateBusinessProfileSettings

Request Body schema:
address
required
string
description
required
string
email
required
string <email>
vertical
required
string
Enum: "Automotive" "Beauty, Spa and Salon" "Clothing and Apparel" "Education" "Entertainment" "Event Planning and Service" "Finance and Banking" "Food and Grocery" "Public Service" "Hotel and Lodging" "Medical and Health" "Non-profit" "Professional Services" "Shopping and Retail" "Travel and Transportation" "Restaurant" "Other"
websites
Array of any

Responses

Response Schema: application/json
address
required
string
description
required
string
email
required
string <email>
vertical
required
string
Enum: "Automotive" "Beauty, Spa and Salon" "Clothing and Apparel" "Education" "Entertainment" "Event Planning and Service" "Finance and Banking" "Food and Grocery" "Public Service" "Hotel and Lodging" "Medical and Health" "Non-profit" "Professional Services" "Shopping and Retail" "Travel and Transportation" "Restaurant" "Other"
websites
Array of any

Request samples

Content type
{
  • "address": "string",
  • "description": "string",
  • "email": "user@example.com",
  • "vertical": "Automotive",
  • "websites": [
    • null
    ]
}

Response samples

Content type
application/json
{
  • "address": "string",
  • "description": "string",
  • "email": "user@example.com",
  • "vertical": "Automotive",
  • "websites": [
    • null
    ]
}

retrieveProfileAbout

Retrieve Profile "about" section

Responses

Response Schema: application/json
text
required
string

Response samples

Content type
application/json
{
  • "text": "string"
}

updateProfileAbout

Update Profile "about" section - only available for admin Users.

Request Body schema:
text
required
string

Responses

Response Schema: application/json
text
required
string

Request samples

Content type
{
  • "text": "string"
}

Response samples

Content type
application/json
{
  • "text": "string"
}

retrieveProfilePhoto

Retrieve Profile Photo - only available for admin Users.

Responses

Response Schema: image/jpeg
binary

updateProfilePhoto

Update Profile Photo - only available for admin Users.

Request Body schema:
file_encoded
required
string <binary>

Binary file

Responses

Request samples

Content type
{
  • "file_encoded": "string"
}

Response samples

Content type
application/json
{ }

deleteProfilePhoto

Delete Profile Photo - only available for admin Users.

Responses

Plugins

retrieveReadOnlyData

This endpoint contains public and read-only data exposed by any Plugin. Plugins expose here any data used in external places, like schemas or templates that do not contain any user-related data, but provide specification or protocol details.

query Parameters
type
required
string

Plugin type, for example: "google" or "hubspot". Choose a type to forward this request to selected plugin.

If the Inbox has a Plugin installed, you can query this plugin public read-only data passing a type parameter.

(any)
any

Any query param you provide here will be used in forwarded Plugin API request

Check the related plugin documentation for response specs.

Responses

Response Schema: application/json
response
object

Plugin response payload

Response samples

Content type
application/json
{
  • "response": { }
}

Authorization

createAuthToken

Request Body schema: application/json
username
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "token": "string"
}