Messages

You can receive and send WhatsApp messages using following endpoints.

post

Create a new mark, marking messages as received.

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

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

Recommended usage

It is recommended to

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

Forwarding messages to your system

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

Instant mark

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

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

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

Authorizations

AuthorizationstringRequired

A user token, sent as Token <token>. Create a user in the admin panel (group App integration) and get its token from POST /api/v1/auth/token/. The channel API key (D360-Api-Key) is not supported.

Body

timestampintegerRequired

A timestamp of the latest message that was received by the User calling this API.

This API cannot mark messages as received for timestamps that are in the future. The message must be first stored in the Inbox in order to mark it as received in the Inbox and then mark as read in WhatsApp. Make sure to not use current timestamp from your local clock as it might be off with the Inbox server clock. The best idea is to use only timestamps from incoming message payload. Only then you can avoid race conditions of marking messages as received while not (yet) receiving them.

customer_wa_idstringRequired

WhatsApp ID of the message sender

Responses

200

No response body

No content

452

Field timestamp value is too far in the future. This API cannot mark messages as received for timestamps that are in the future. The message must be first stored in the Inbox in order to mark it as received in the Inbox and then mark as read in WhatsApp. Make sure to not use current timestamp from your local clock as it might be off with the Inbox server clock. The best idea is to use only timestamps from incoming message payload. Only then you can avoid race conditions of marking messages as received while not (yet) receiving them.

application/json

453

Contact of given customer_wa_id does not exist

application/json

post/api/v1/mark_as_received/

POST /api/v1/mark_as_received/ HTTP/1.1
Host: your-stack.inbox.getchat.360dialog.io/
Authorization: Token YOUR_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "timestamp": 1,
  "customer_wa_id": "text"
}

No content

get

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

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

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

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

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

Messages are ordered from newest to oldest.

Recommended usage

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

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

/api/v1/messages/?limit=20

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

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

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

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

Authorizations

AuthorizationstringRequired

Query parameters

assigned_groupintegerOptional

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

assigned_to_mebooleanOptional

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

before_timeintegerOptional

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

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

chat_tag_idintegerOptional

Filter only Messages of Chats having given tag ID.

from_usbooleanOptional

Filter only Messages that are either from us (inbox users and automation) or not.

limitintegerOptional

Number of results to return per page.

mark_as_receivedintegerOptional

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

offsetintegerOptional

The initial index from which to return the results.

searchstringOptional

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

The API will search in following places:

text.body field of waba_payload JSON
{media_type}.caption or {media_type}.filename of media type message fields: image, document, audio, video ,voice, sticker"
name field of each Tag in tags field of each Message

since_timeintegerOptional

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

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

wa_idstringOptional

WhatsApp id of related contact

Responses

200Success

application/json

countintegerRequiredExample: 123

nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?offset=400&limit=100

previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?offset=200&limit=100

452

The contact does not exist

application/json

get/api/v1/messages/

GET /api/v1/messages/ HTTP/1.1
Host: your-stack.inbox.getchat.360dialog.io/
Authorization: Token YOUR_TOKEN
Accept: */*

{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "count": 1,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": "76b47063-3ddd-491e-8151-cdaf1c2b73b2",
          "waba_payload": {
            "wa_id": "48123123123",
            "to": "48123123123",
            "type": "text",
            "text": {
              "body": "Hello :)"
            },
            "id": "gBGGSFEBeRJ_AgnJkfda1iRwQteM",
            "timestamp": "1611319126"
          },
          "waba_statuses": {
            "sent": null,
            "delivered": null,
            "read": null
          },
          "contact": {
            "wa_id": "48123123123",
            "waba_payload": {
              "profile": {
                "name": "Konrad"
              },
              "wa_id": "48123123123"
            },
            "initials": "K",
            "last_message_timestamp": 1685296667
          },
          "customer_wa_id": "48123123123",
          "from_us": false,
          "received": true,
          "sender": {
            "url": "http://baseurl/api/v1/users/1/",
            "id": 1,
            "username": "konrad",
            "first_name": "Konrad",
            "last_name": "Rabbit",
            "email": "rabbit@example.com",
            "profile": {
              "role": "admin"
            },
            "groups": [
              {
                "id": 2,
                "name": "Admin"
              }
            ],
            "permissions": {
              "can_use_tags": true,
              "can_read_chats": "all",
              "can_write_to_chats": "all"
            }
          }
        }
      ]
    }
  ]
}

post

Create a new message

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

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

If the recipient does not have WhatsApp, the resulting WhatsApp Business API error (WhatsApp Business API Client Error Code 470) will be forwarded to you asynchronously using another channel (e.g. websocket).

Authorizations

AuthorizationstringRequired

Body

typestring · enumRequired

text - text
image - image
contacts - contacts
document - document
hsm - hsm
location - location
sticker - sticker
template - template
audio - audio
video - video
interactive - interactive
reaction - reaction

Possible values:

verify_contactboolean · nullableOptional

Deprecated parameter: Will be treated as false regardless of value, as contact verification has been removed from WhatsApp side.

See endpoint description. It has been updated to reflect the new workflow.

Default: false

contactsanyOptional

See Contact Messages WhatsApp Business API Documentation

hsmanyOptional

Deprecated: The hsm object has been deprecated with v2.39 of the WhatsApp Business API.See 2.39.1 changelog and WhatsApp Business API Documentation.

locationanyOptional

See Location Messages WhatsApp Business API Documentation

templateanyOptional

See Template Messages WhatsApp Business API Documentation

interactiveanyOptional

See interactive object in WhatsApp Business API Documentation

wa_idstringRequired

WhatsApp ID of the message recipient — either a phone number in canonical form (e.g. 48123123123) or a Business-Scoped User ID (e.g. US.13491208655302741918).

Pattern: ^([A-Z]{2}\.(ENT\.)?[a-zA-Z0-9]+|[0-9]+)$

Responses

200

Message sent.

DEPRECATED: This endpoint either replies with 202 status code or other documented codes.

No content

202

Message is added to the queue and will be sent soon.

Note that this doesn't indicate that the message is sent. Await message "statuses" events to determine when message is sent, received and read by recipient. Note that you need to inspect "getchat_id" value inside received "statuses" events, in order to be able to relate statuses with outgoing messages.

application/json

400

User error. Please check your request and API response.

There are various scenarios for 400 status code and the API reply will provide as precise information on the client-side error as possible. For example, if JSON data is not provided, "reason" field is returned with "JSON data not provided" as reason value. If there are problems with specific fields, those are denoted with their names in the API response payload. Every field can have multiple errors, so those error messages are provided in a list (see 400 response examples).

application/json

403

You have no permission to send messages to this Chat.

Check your User account settings. Each User needs to have permissions specified - if the User can read from or write to Chats.

application/json

423

Queue is full. Your quota is full of pending messages.

Your quota is limited (by default) to 1.5M messages stored permanently. When you reach your quota, the oldest messages in your storage are removed when they are over quota. You can reach your quota by either receiving or sending messages. When sending, messages are first added to the queue and then they are propagated to WhatsApp. If you are too fast, you might end up with entire quota (by default 1.5 million) of messages consisting of pending messages. This leads to a situation when you no longer can add messages to the queue, because it would remove not-yet-sent messages from your storage. Normally, this condition is hard to be met, but can be met easily if your WhatsApp Business API endpoint has been blocked by Meta for some reason, or the endpoint has some performance issues.

application/json

453

Customer care messaging window expired.

You can message WhatsApp users with session messages only while the customer care messaging window is open. Outside this window, only template messages are allowed.

Do not assume a fixed duration: the window depends on what opened the conversation (an ad click lasts considerably longer than an organic message) and Meta changes it over time. Read messaging_window_expires_at from the Chat's contact instead.

application/json

503

The message gateway could not be reached.

Retry after a few seconds. Read the Chat's messages first if you need to be certain: a request that timed out rather than being refused may have queued the message before the gateway stopped answering.

application/json

post/api/v1/messages/

POST /api/v1/messages/ HTTP/1.1
Host: your-stack.inbox.getchat.360dialog.io/
Authorization: Token YOUR_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "wa_id": "48123123123",
  "type": "text",
  "text": {
    "body": "Hello!"
  }
}

No content

get

Get a single Message by its Inbox message ID.

Authorizations

AuthorizationstringRequired

Path parameters

idstringRequired

A unique value identifying this message.

Responses

200Success

application/json

idstringRequired

Internal Inbox Message ID

waba_payloadanyRequired

See Inbound Notifications from WhatsApp Business API

from_usbooleanRead-onlyRequired

Allows to easily implement different display for messages sent by us or by customer.

receivedbooleanOptional

Tells if this message was marked as received by you (currently logged in user)

Default: false

before_timeintegerOptional

since_timeintegerOptional

customer_wa_idstringRead-onlyRequired

Deprecated

sent_by_mbabooleanRead-onlyRequired

This message was sent on the business's behalf by Meta Business Agent (the copy arrived on the standby webhook field). Only set when from_us is true; distinguishes AI messages from ones sent by inbox users or automation.

get/api/v1/messages/{id}/

GET /api/v1/messages/{id}/ HTTP/1.1
Host: your-stack.inbox.getchat.360dialog.io/
Authorization: Token YOUR_TOKEN
Accept: */*

200Success

{
  "id": "text",
  "waba_payload": null,
  "waba_statuses": {
    "sent": 1,
    "delivered": 1,
    "read": 1
  },
  "contact": {
    "wa_id": "text",
    "bsuid": "text",
    "phone_number": "text",
    "waba_payload": {
      "profile": {
        "name": "text"
      },
      "wa_id": "text"
    },
    "initials": "text",
    "last_message_timestamp": 1,
    "messaging_window_expires_at": 1,
    "messaging_window_origin": "text",
    "resolved": true
  },
  "from_us": true,
  "received": false,
  "sender": {
    "url": "https://example.com",
    "id": 1,
    "username": "text",
    "first_name": "text",
    "last_name": "text",
    "email": "name@gmail.com",
    "profile": {
      "role": "user",
      "is_available": true
    },
    "groups": [
      {
        "id": 1,
        "name": "text"
      }
    ],
    "permissions": {
      "can_use_tags": true,
      "can_read_chats": "all",
      "can_write_to_chats": "all"
    },
    "assigned_wa_ids": [
      "text"
    ]
  },
  "before_time": 1,
  "since_time": 1,
  "customer_wa_id": "text",
  "tags": [
    {
      "name": "text",
      "web_inbox_color": "text",
      "tagging_id": 1,
      "id": 1,
      "extra": null
    }
  ],
  "chat_tags": [
    {
      "name": "text",
      "web_inbox_color": "text",
      "tagging_id": 1,
      "id": 1,
      "extra": null
    }
  ],
  "sent_by_mba": true
}

PreviousWhats App Accounts

NextPersons

Last updated 5 days ago

Was this helpful?