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

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.

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.

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

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

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.

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.

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

• get List WABA Webhooks
• post Create WABA Webhook
• get Retrieve WABA Webhook
• put Update WABA Webhook
• del Delete 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"
    }
  ]
}

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

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

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.

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

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:

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

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.

Chat participants who contacted your inbox via WhatsApp

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.

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