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

Your deployment documentation might differ if you participate in our beta program.

Note that you can participate in our beta program only if you directly ask us. If you don't participate, the API is the same as in publicly available documentation.

For your instance-specific docs, go to https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/api/.

To get YOUR_STACK_NAME value, check the URL of your inbox instance or URL of your instance admin panel.

A missing puzzle piece

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:

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.5 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.5 million 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.

Your inbox is reachable at https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/ and all API endpoints are reachable at https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/api/v1/.

For example, sending a POST to /api/v1/auth/token/ means sending a POST to https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/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.

Currently, there are three ways of authorization available:

• Token (should be preferred)
• Session
• Provider

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

There are two ways to create a new User:

• See post Create a New User endpoint
• or create a new User using the Admin Panel

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.

• See post Create Auth Token for request body schema

Example:

curl -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST \
    https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/api/v1/auth/token/ \
    --data "{\"username\": \"peter\", \"password\": \"secret\"}"

When valid username and password are provided, API reply with 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.

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 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_STACK_NAME}.inbox.getchat.360dialog.io/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_STACK_NAME}.inbox.getchat.360dialog.io/api/v1/users/current/ \
    | python -m json.tool

{
    "url": "https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/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"
    }
}

Each endpoint described later in the docs has to be accessed with HTTP Request with SSL and one of available authorization methods: Token, Session or Provider.

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

Base URL shown in this documentation is https://{ YOUR_STACK_NAME }.inbox.getchat.360dialog.io/

To get YOUR_STACK_NAME value, check the URL of your inbox instance or URL of your instance admin panel.

Example for GET request with curl:

curl \
    -H "Authorization: Token 8aeb44f5a318542d32bb13019d68198467ee21f0" \
    -X GET \
    https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/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_STACK_NAME}.inbox.getchat.360dialog.io/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.

You should start with /chats/ endpoint:

curl -H "Authorization: Token 8aeb44f5a318542d32bb13019d68198467ee21f0" \
    -X GET \
    https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/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_STACK_NAME}.inbox.getchat.360dialog.io/api/v1/messages/?wa_id=48123123123&limit=1 \
    | python -m json.tool

{
    "count": 276,
    "next": "http://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/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_STACK_NAME}.inbox.getchat.360dialog.io/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_STACK_NAME}.inbox.getchat.360dialog.io/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_STACK_NAME}.inbox.getchat.360dialog.io/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.

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.

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.

How Multiple Webhooks are called

Each WABA Webhook is configured per API user - Your Chatbot, Your CRM System etc.

One user can have multiple WABA Webhook configs, for example:

[{
    "id": 1,
    "user": {"id": 23, "username": "string", "url": "string"},
    "url": "http://example.com",
    "on_incoming_message": true,
    "on_outgoing_message": false,
    "on_assigned": false
}, {
    "id": 2,
    "user": {"id": 23, "username": "string", "url": "string"},
    "url": "http://example.com",
    "on_incoming_message": false,
    "on_outgoing_message": true,
    "on_assigned": false,
    "headers": {}
}, {
    "id": 3,
    "user": {"id": 23, "username": "string", "url": "string"},
    "url": "http://example.com",
    "on_incoming_message": false,
    "on_outgoing_message": false,
    "on_assigned": true,
    "headers": {"Authorization": "Token 8aeb44f5a318542d32bb13019d68198467ee21f0"}
}]

or you can have following webhooks:

[{
    "id": 1,
    "user": {"id": 23, "username": "string", "url": "string"},
    "url": "http://example.com",
    "on_incoming_message": true,
    "on_outgoing_message": true,
    "on_assigned": false
}, {
    "id": 2,
    "user": {"id": 23, "username": "string", "url": "string"},
    "url": "http://example.com",
    "on_incoming_message": false,
    "on_outgoing_message": false,
    "on_assigned": true,
    "headers": {"Authorization": "Token 8aeb44f5a318542d32bb13019d68198467ee21f0"}
}]

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:

• get List WABA Webhooks
• post Create WABA Webhook
• get Retrieve WABA Webhook
• put Update WABA Webhook
• del Delete WABA Webhook
• get Test WABA Webhook

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"
    }
  ]
}

Standard Webhook Events and Notifications from 360Dialog are forwarded intact from the inbox to every Webhook configured with "cloud_api" events, with several extensions - new fields are added to the payload to provide more context.

"messages" - new fields are added to each message object:

• "is_assigned_to_user" (boolean) - true if the contact is assigned to a specific user, false otherwise.
• "is_assigned_to_group" (boolean) - true if the contact is assigned to a specific group, false otherwise.
• last_message_from_us_timestamp (string, nullable) - timestamp of the last message we sent to this contact through this Inbox, null if this never happened

Example:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "changes": [
        {
          "value": {
            "messages": [
              {
                "from": "48123123123",
                "id": "wamid.ID",
                "timestamp": "1631105256",
                "text": {"body": "MESSAGE_BODY"},
                "type": "text",
                "is_assigned_to_user": true,
                "is_assigned_to_group": false,
                "last_message_from_us_timestamp": "1631105255"
              }
            ]
          }
        }
      ]
    }
  ]
}

"statuses" - a new field is added: "getchat_id" that will help you link messages and statuses using get.chat's internal message ID. This ID is returned by post Create Message endpoint so that you can easily link this message to a status, even if the message was only added to the queue and hasn't yet been sent to WhatsApp.

Example:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "statuses": [
        {
          "id": "gBEGkFO33SUyAgm0lj123TmE5lc",
          "getchat_id": "8b176ba5-fa8e-458e-94ad-85d1ae8f3be0",
          "recipient_id": "48123123123",
          "status": "read",
          "timestamp": "1634833334",
          "type": "message"
        }
      ]
    }
  ]
}

Apart from "getchat_id", the Integration API does not make any other changes to "cloud_api" events and notifications, allowing you to integrate with WhatsApp Business API as if there was no get.chat between your webhook receiver and 360Dialog.

Deprecated (On-Prem) Webhook definition, provides three fields: "contacts", "messages" and "statuses" notifications. 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.

Additional fields to original events:

• "messages" - new fields are added to each message object:
  • "is_assigned_to_user" (boolean) - true if the contact is assigned to a specific user, false otherwise.
  • "is_assigned_to_group" (boolean) - true if the contact is assigned to a specific group, false otherwise.
  • last_message_from_us_timestamp (string, nullable) - timestamp of the last message we sent to this contact through this Inbox, null if this never happened

Example:

{
    "messages": [
        {
            "from": "sender-wa-id",
            "id": "message-id",
            "timestamp": "message-timestamp",
            "type": "text",
            "text": {
                "body": "text-message-content"
            },
            "is_assigned_to_user": true,
            "is_assigned_to_group": false,
            "last_message_from_us_timestamp": "1631105255"
        }
    ]
}

• "statuses" - a new field is added: "getchat_id" that will help you link messages and statuses using get.chat's internal message ID. This ID is returned by post Create Message endpoint so that you can easily link this message to a status, even if the message was only added to the queue and hasn't yet been sent to WhatsApp.

Example:

{
    "statuses": [
      {
        "id": "gBEGkFO33SUyAgm0lj123TmE5lc",
        "getchat_id": "8b176ba5-fa8e-458e-94ad-85d1ae8f3be0",
        "recipient_id": "48123123123",
        "status": "read",
        "timestamp": "1634833334",
        "type": "message"
      }
    ]
}

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 get.chat 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.

• "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!

• "tagged_messages" deprecated, use "message_tagging"

• "tagged_chats" deprecated, use "chat_tagging"

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, use "message_tagging"

• "tagged_chats" deprecated , use "chat_tagging"

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

POST /

{
  "outgoing_messages": [
        {
            "id": "8e04bff7-9a07-486b-90a4-09c2e5d85e69",
            "waba_payload": {
                "preview_url": false,
                "recipient_type": "individual",
                "to": "48123123123",
                "type": "image",
                "image": {
                    "link": "http://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/api/v1/media/e4b60f1d-1847-4233-8a88-58e123123123"
                },
                "id": "gBGGSFEBeRJ_AglpKKJ1s123123",
                "timestamp": 1612372697
            },
            "waba_statuses": {
                "sent": null,
                "delivered": null,
                "read": null
            },
            "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_STACK_NAME}.inbox.getchat.360dialog.io/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"
        },
        {
            "id": "e6a310b5-b184-4381-bb83-60ee2d0cff13",
            "waba_payload": {
                "preview_url": false,
                "recipient_type": "individual",
                "to": "48123123123",
                "type": "image",
                "image": {
                    "link": "http://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/api/v1/media/bc4bd93e-a522-4bce-aac8-cc1123123123"
                },
                "id": "gBGGSFEBeRJ_AgnJK-don123123",
                "timestamp": 1612372571
            },
            "waba_statuses": {
                "sent": null,
                "delivered": null,
                "read": null
            },
            "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_STACK_NAME}.inbox.getchat.360dialog.io/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 "message_tagging" event:

(See get List Message Tagging Events API endpoint results Array entries to learn more)

POST /

{
    "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":
                {
                    "role": "user"
                },
                "groups":
                [
                    {
                        "id": 0,
                        "name": "string"
                    }
                ],
                "permissions":
                {
                    "can_use_tags": true,
                    "can_read_chats": "all",
                    "can_write_to_chats": "all"
                }
            }
        }
    ]
}

Example payload of a Webhook call containing "chat_tagging" event.

(get List Chat Tagging Events API endpoint (results Array entries))

POST /

{
    "chat_tagging":
    [
        {
            "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":
                {
                    "role": "user"
                },
                "groups":
                [
                    {}
                ],
                "permissions":
                {
                    "can_use_tags": true,
                    "can_read_chats": "all",
                    "can_write_to_chats": "all"
                }
            }
        }
    ]
}

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!

• See how number of new messages is provided in get List Chats endpoint.
• Learn more how to mark messages as received using post Create Received Message Mark

In order to integrate a bot, you'll need the following steps:

1. Create a new Inbox User for this bot
2. Create a Webhook for your bot
3. Implement an auto-responder

See chapters below to get to know how to do every step.

There is also a variety of customization you can do, apart from above 3 simple steps.

For example, you can:

1. Hand over conversations between human agents, and bot.
2. Hide the bot conversations from human agents, or show it for human users, so that the conversation can be reviewed.

See further chapters below for more information about mentioned customization.

Create a new Inbox User for your bot

There are two ways to create a new User for your bot:

• via the API
• via the Admin Panel

Create a new Inbox User for your bot - via the API

Use post Create a New User endpoint.

When creating, provide "app" in "profile" > "role" field. For example:

{
  "username": "My Bot",
  "profile": {
    "role": "app"
  }
}

Save the "activation_url" returned by the API call.

Call the "activation_url" with HTTP GET request. 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. If you want, you can set up a password for this user, but it's not required. To change the password, use changeUserPassword endpoint.

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

Create a new Inbox User for your bot - via the Admin Panel

You can create a new bot User via the Admin Panel, in the "Users" section:

1. Click "Add user"
2. Username field: Give the bot some friendly user name, so that human users can recognize the bot messages are coming from an automation
3. Password and Password confirmation - enter a new secure password
4. Groups: Click "Add another Group"

See Accessing the API > Authorization section for information on how to acquire a Token for the new user.

Create a Webhook for your bot

To create a Webhook for your bot, you have two options:

• via the API
• via the Admin Panel

Create a Webhook for your bot - via the API

Use post Create WABA Webhook endpoint.

When creating, provide "on_assigned": true, and you can also consider "on_incoming_message": true, for example:

{
  "url": "http://mywebhook.example.com",
  "on_incoming_message": true,
  "on_outgoing_message": false,
  "on_assigned": true,
  "headers": {}
}

More information about the use of the above fields is provided in the next chapters.

If you want your bot to react to more events than just incoming messages, configure your Webhook accordingly.

Create a Webhook for your bot - via the Admin Panel

Create a new Webhook via the Admin Panel, in the "WABA Webhooks" section:

1. Click "Add WABA webhook"
2. User field: Select your bot User in this field
3. Select all the events you want to receive. "On assigned" should be a good choice for this bot, and "On incoming message" can be also considered. More information about the use of those fields is provided in the next chapters.
4. Provide the webhook URL
5. Click "SAVE"

If you want your bot to react to more events than just incoming messages, select the events accordingly.

Implement an auto-responder

To implement an auto-responder with your bot User, call the following API endpoint whenever a new webhook is received on your end:

Use post Create Message endpoint.

The WABA Webhook extension provides many types of events. Your Webhook will receive "assigned_messages" event wheneve a new inbox arrives to a Chat currently assigned to your bot. You will receive "incoming_messages" event whenever a new incoming message arrives to the entire inbox.

To make sure that your bot replies only when it is expected, you have various options to consider:

1. Let the human users manage the automation. Inbox agents can assign a Chat to other Users, including your bot User.
2. Set up an auto reply when human agents are unavailable, or every time a new conversation is started.

See below chapters for more information.

Hand over conversations between human agents and bot

Inbox agents can assign a Chat to other Users, including your bot User. You can implement your bot reacting to this, with "assigned_messages" event.

A Webhook request with "assigned_messages" payload will show up whenever new Messages arrives to the Chat that is currently assigned to the bot User receiving this Webhook and also when one or more Chats are assigned to the User just now.

On your end, implement your bot reacting to the "assigned_messages" event. Implement your business logic for checking if a new conversation is started, or an existing one is continued. You can utilize all endpoints from the API when needed.

In case you need an auto-responder to reply when human agents are unavailable, you will need to implement it with reacting to "incoming_messages" event.

A considerable implementation can be the following:

1. Receive an "incoming_messages" (or "messages") event on your Webhook end.
2. Call retrieveChatAssignment endpoint to get to know if related Chat is assigned to a human user already.
3. If the Chat is already assigned, implement your business logic to decide if the bot should join the conversation by themselves. For example, if human agents are not responding after a defined amount of time.
4. If the Chat is not assigned, assign it to the bot using partialUpdateChatAssignment endpoint.
5. After this point, you will receive an "assigned_messages" event, so it's recommended that your bot reacts to that. If you need, you can of send an additional message here, when a conversation is picked up by the bot automatically.

Hide or show conversations with a bot, from/to human agents

In some use cases, conversations should be hidden from human users when handled by a bot. In other integrations, users want to see the auto-replied conversations so that the conversations could be reviewed.

To hide the conversations when they are assigned to a bot, you need to change the permissions for "Regular user" group.

To do this via the Admin Panel, go to the "Groups" section, choose "Regular user" and set "Can read chats:" to "Only Chats assigned to User's Groups".

To do this via the API, use "partialUpdateUser" endpoint, and provide "permissions" > "can_read_chats" equal to "group". For example:

{
  "permissions": {
    "can_use_tags": true,
    "can_read_chats": "group",
    "can_write_to_chats": "group"
  }
}

On the bot end, implement a business logic that makes the Chat visible or hidden to the "Regular users". To do this, use partialUpdateChatAssignment endpoint.

For example:

{
  "wa_id": "123123123",
  "assigned_group": 1
}

where "123123123" is a related chat wa_id, and the "Regular users" group ID is 1.

Implement the following update when Chat needs to be hidden from "Regular users" group:

{
  "wa_id": "123123123",
  "assigned_group": 0
}

A Websockets Server is available at wss://websockets-{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/

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

Websockets protocol

get.chat 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.

{"token": "8aeb44f5a318542d32bb13019d68198467ee21f0"}

{
    "type": "response",
    "status": "bad_request", 
    "message": "Expecting value: line 1 column 1 (char 0)"
}

{
    "type": "token", 
    "status": "success", 
    "message": "Welcome, peter!"
}

{
    "type": "token", 
    "status": "failed", 
    "message": "Token matching query does not exist."
}

{
    "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

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.

In scenarios like embedding the inbox web frontend inside an external app, a password-less authentication flow might come useful. In this flow, the end user doesn't have to provide (and remember) inbox user password, and user authentication is fully managed by the external app developed by the Partner, or app provider.

To implement that, Refresh Token can be used in a standardized password-less authentication flow:

Password-less authentication flow

1. Authentication challenge: The Client User opens the Partner's website Front End. (Arrow: 1. Open website) The Frontend sends an authentication challenge (e.g. asks for user's password) when the User tries to access the website, or the User is already authenticated on Partner Front End.
2. User authentication: The user proves their identity by logging in on the Partner's Front End, or User is already authenticated. Partner Front End gets the Inbox URL for related User, from Partner Back End (Arrow: 2. Get Inbox URL).
3. Challenge response: The User's authentication to the Partner app, allows to acquire an authentication to the Inbox API. Partner Back End gets the current Refresh Token (using retrieveRefreshToken endpoint) for this authenticated User, using service account (admin) credentials (Arrow: 3. Get or Set Refresh Token for User X).
4. Response validation: The Inbox API uses the service account credentials and User ID to return with Refresh Token (Arrow: 4. Reply with Refresh Token for User X).
5. After Inbox API call, the Inbox URL is known and is combined with acquired Refresh Token (using idt GET parameter). (Arrow: 5. [Display / Embed / Redirect User to] URL). For example, if API call was made to https://{INBOX_URL}/api/v1, then the Inbox URL should be https://{INBOX_URL}/app?idt={REFRESH_TOKEN}.
6. The Inbox URL + Refresh Token is displayed to the User - either as a link or button, or embedded inside an iframe, or returned as a redirect. (Arrow: 6. [Embed / Redirect User to] URL)
7. Optionally, the User is redirected to Inbox URL in a new tab or popup. (Arrow: 7. Optionally Redirect User to Inbox URL)

For proof-of-concept reasons, it is possible to implement an even simpler flow, without the dynamic communication with Inbox API needed:

Password-less authentication flow - Quick Start

In this version, everything is the same as in the full version, except the point 3. and with point 4. removed.

In point 3., the Refresh Token value can be retrieved from a database or any other backend storage that was populated previously. For proof of concept purposes, such database entry or other storage entry could be prepared manually by a developer, or automatically via API calls in some initial process before this flow.

In other words, retrieveRefreshToken endpoint is used like in the full version of the flow, but only once - before authentication flow.

How does the Partner Back End know the Inbox API URL and credentials?

Every Inbox has its own URL, and its own API URL, that is bound to a specific inbox instance (and WhatsApp Business phone number). That being said, the relationship of Client User <-> Inbox URL must be stored somewhere in the Partner Back End before authentication flow, ideally during Client User registration process, or account creation process.

When authenticating the Client User during password-less authentication flow, Partner Back End will need to know the Inbox API URL that is unique for every WhatsApp Business phone number. In addition to URL, Partner Back End will need to authenticate itself towards API using one of the provided Authorization methods. It is recommended to use Provider method, which is suitable for Partners who are using 360dialog API Key with 360dialog API. In Provider Method, the Partner Back End will pass the 360dialog API Key to Inbox API, and Inbox API will use that Key to confirm that the Partner has valid rights to the API.

It's possible to implement Password-less authentication flow without Provider Authorization Method, and by using one of two other methods (Token, and Session), however those two methods are not recommended for password-less authentication flow, as they may make the implementation of the flow much more complex. Both Token and Session authorization methods will require to store additional credentials at Partner Back End. With Provider Authorization Method, an integration of Partner System with Inbox API is much easier to implement, as the developer doesn't have to distinguish between Inbox API credentials and 360dialog API credentials. It is also much easier to maintain, in case of resetting API credentials. When Partner (or Client) decides to reset the 360dialog API Key, Provider Method is aware of that, and will properly authenticate the Partner Back End with a new 360dialog API Key.

In step 5. of the flow, the documentation says "the Inbox URL is known" - how exactly the URL can be known?

Note that in step 3., Partner Back End is making a request to Inbox API. This request is made to an API that is exposed on an URL that is uniquely bound to a specific inbox instance (and WhatsApp Business phone number). That being said, the Client User <-> Inbox URL relationship must be stored somewhere in Partner Back End before authentication flow, ideally during Client User registration process, or account creation process. See "How does the Partner Back End know the Inbox API URL and credentials?" for more information.

In step 5., the Inbox URL is already known, because it was used in step 3. So, the Inbox URL can be re-used in steps 5., 6., and 7. without reaching out to database or storage again.

For example, if API call was made to https://{INBOX_URL}/api/v1, then the Inbox URL should be https://{INBOX_URL}/app/?idt={REFRESH_TOKEN}.

How to handle situations when Client User changed their password?

Partner app is in a full control of password-less authentication flow. On 1st step of the flow, the Partner Front End and Partner Back End are authenticating the Client User. The Partner app (or the Partner system) has to handle the password exceptions on their own - for scenarios like password reset, forgotten password and similar.

How to prevent Client Users from logging into the Inbox (or Inbox API) with Inbox-internal username and password?

New Client Users can be created using Partner's automation with createNewUser endpoint or manually via Inbox admin panel. Both methods allow for creating a new User without any password set, which prevents from logging into the Inbox outside of Partner systems or Partner app.

In other words, when a new User is created in an Inbox without password, then it's possible to log in to this User only via password-less authentication flow and via one-time Activation URL (See activation_url in createNewUser endpoint documentation).

Endpoints related to Authorization

WhatsApp Accounts of your inbox

You can receive and send WhatsApp messages using following endpoints.

WhatsApp Users who contacted your Inbox

WhatsApp Users' contact details

get.chat WhatsApp 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.

In the /contacts/ section, there are also WhatsApp Business API provided endpoints like: verifying the Contact, blocking WhatsApp number, reporting WhatsApp user to Meta.

Existing conversations with WhatsApp Users