Chats

Existing conversations with WhatsApp Users

post

Import an existing WhatsApp chat generated by the "Export chat" action in the WhatsApp Business app.

Use this endpoint to upload the chat and all media files. Requires some preparation work to be done in the app that served as export target for WhatApp.

Parameters you supply such as contacts, UTC offset must come from the device you exported the WhatsApp chat on.

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

chat_textstringRequired

The text chat log as given to you by WhatsApp

utc_offset_minutesintegerRequired

The device may have had a non-UTC time zone; supply the number of minutes that time zone is ahead of UTC. Supply a negative number if you are in the Americas

device_language_codestringRequired

Locale code of device's system language, and optionally, country

Responses

201Success

application/json

new_messagesintegerRequired

The number of messages not received by currently authenticated user

wa_idstringRequired

Deprecated

bsuidstring · nullableRead-onlyRequired

Business-Scoped User ID for this contact. Populated from the webhook's user_id field. Stable across phone number changes for the same user-portfolio pair, so this is the most reliable long-term identifier.

phone_numberstring · nullableRead-onlyRequired

Phone number when known. Equals wa_id for phone-primary contacts. For BSUID-primary contacts (where wa_id is a BSUID), populated when WhatsApp shares the phone number — e.g. recent interaction within the last 30 days, or via Contact Book.

thread_controllerone of · nullableRead-onlyRequired

Who currently responds in this conversation: mba while Meta Business Agent holds control, inbox after an agent took over. null means Meta Business Agent was never involved in this chat.

mba - Meta Business Agent
inbox - Inbox

string · enumOptional

mba - Meta Business Agent
inbox - Inbox

Possible values:

undefined · enumOptionalPossible values:

post/api/v1/chat_import/

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

{
  "chat_text": "10/03/2022, 11:00 - Customer 1: Message 1\n10/03/2022, 11:00 - Customer 1: Message 2 Line 1\nMessage 2 Line 2",
  "chat_participants": [
    {
      "handle": "Customer 1",
      "phone_number": "+00 000 00000000"
    }
  ],
  "utc_offset_minutes": -420,
  "device_language_code": "en-US",
  "media_files": [
    {
      "b64_content": "AA==",
      "mime_type": "image/jpg",
      "file_name": "IMG-20220310-WA0000.jpg"
    }
  ]
}

201Success

{
  "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
  },
  "new_messages": 1,
  "wa_id": "text",
  "bsuid": "text",
  "phone_number": "text",
  "last_message": {
    "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
  },
  "assigned_to_user": {
    "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"
    ]
  },
  "assigned_group": {
    "id": 1,
    "name": "text"
  },
  "tags": [
    {
      "name": "text",
      "web_inbox_color": "text",
      "tagging_id": 1,
      "id": 1,
      "extra": null
    }
  ],
  "thread_controller": "mba"
}

get

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

This endpoint is similar to /persons/ endpoint - here also contacts are listed, but only these contacts for which conversation already exists.

Chats are sorted by last_message_timestamp, newest to oldest.

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

Marking messages as received is important to prevent duplicate notifications.

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

Authorizations

AuthorizationstringRequired

Query parameters

assigned_groupintegerOptional

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

assigned_to_mebooleanOptional

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

blockedbooleanOptional

Filter only Chats which are blocked due to spam and abuse of WhatsApp.

chat_tag_idintegerOptional

Filter only Chats having given tag ID.

limitintegerOptional

Number of results to return per page.

message_has_referralbooleanOptional

When set to true, only Chats having Message with referral object are returned.

message_referral_bodystringOptional

Filter only Chats that had a Message with referral.body, and the last such Message had referral.body equal to given param.

message_referral_headlinestringOptional

Filter only Chats that had a Message with referral.headline, and the last such Message had referral.headline equal to given param.

message_referral_media_typestringOptional

Filter only Chats that had a Message with referral.media_type, and the last such Message had referral.media_type equal to given param. Possible values are "image" and "video".

message_referral_source_idstringOptional

Filter only Chats that had a Message with referral.source_id, and the last such Message had referral.source_id equal to given param.

message_referral_source_typestringOptional

Filter only Chats that had a Message with referral.source_type, and the last such Message had referral.source_type equal to given param. Possible values are "ad" and "post".

message_referral_source_urlstringOptional

Filter only Chats that had a Message with referral.source_url, and the last such Message had referral.source_url containing phrase of message_referral_source_url. For example, message_referral_source_url=asd matches referral.source_url = https://asd.com

messages_before_timeintegerOptional

POSIX timestamp. Returns only Chats containing Messages that are older than specified value.

messages_since_timeintegerOptional

POSIX timestamp. Returns only Chats containing Messages at the same timestamp or newer than specified value.

offsetintegerOptional

The initial index from which to return the results.

reportedbooleanOptional

Filter only Chats which are reported due to spam and abuse of WhatsApp.

searchstringOptional

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

The API will search in following places:

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

unreadbooleanOptional

Filter only Chats that have unread messages.

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

get/api/v1/chats/

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

200Success

{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "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
      },
      "new_messages": 1,
      "wa_id": "text",
      "bsuid": "text",
      "phone_number": "text",
      "last_message": {
        "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
      },
      "assigned_to_user": {
        "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"
        ]
      },
      "assigned_group": {
        "id": 1,
        "name": "text"
      },
      "tags": [
        {
          "name": "text",
          "web_inbox_color": "text",
          "tagging_id": 1,
          "id": 1,
          "extra": null
        }
      ],
      "thread_controller": "mba"
    }
  ]
}

get

Get one Chat, including its contact, the number of new messages, its assignment and its tags.

Authorizations

AuthorizationstringRequired

Path parameters

wa_idstringRequiredPattern: ^[^/]+$

Responses

200Success

application/json

new_messagesintegerRequired

The number of messages not received by currently authenticated user

wa_idstringRequired

Deprecated

bsuidstring · nullableRead-onlyRequired

phone_numberstring · nullableRead-onlyRequired

thread_controllerone of · nullableRead-onlyRequired

Who currently responds in this conversation: mba while Meta Business Agent holds control, inbox after an agent took over. null means Meta Business Agent was never involved in this chat.

mba - Meta Business Agent
inbox - Inbox

string · enumOptional

mba - Meta Business Agent
inbox - Inbox

Possible values:

undefined · enumOptionalPossible values:

get/api/v1/chats/{wa_id}/

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

200Success

{
  "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
  },
  "new_messages": 1,
  "wa_id": "text",
  "bsuid": "text",
  "phone_number": "text",
  "last_message": {
    "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
  },
  "assigned_to_user": {
    "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"
    ]
  },
  "assigned_group": {
    "id": 1,
    "name": "text"
  },
  "tags": [
    {
      "name": "text",
      "web_inbox_color": "text",
      "tagging_id": 1,
      "id": 1,
      "extra": null
    }
  ],
  "thread_controller": "mba"
}

post

Hands control of this conversation back to Meta Business Agent.

The reverse direction needs no endpoint: the inbox takes control of a conversation simply by sending a message to it.

Authorizations

AuthorizationstringRequired

Path parameters

wa_idstringRequiredPattern: ^[^/]+$

Responses

200

Thread control passed to the Inbox

application/json

thread_controllerstringOptionalExample: mba

post/api/v1/chats/{wa_id}/handover/

POST /api/v1/chats/{wa_id}/handover/ HTTP/1.1
Host: your-stack.inbox.getchat.360dialog.io/
Authorization: Token YOUR_TOKEN
Accept: */*

200

Thread control passed to the Inbox

{
  "thread_controller": "mba"
}

patch

Marks a chat as resolved, or removes this mark.

Authorizations

AuthorizationstringRequired

Path parameters

wa_idstringRequiredPattern: ^[^/]+$

Body

wa_idstringRead-onlyOptional

WhatsApp ID — either a phone number in canonical form (e.g. 48123123123) or a Business-Scoped User ID (e.g. US.13491208655302741918) for users who have hidden their phone number.

bsuidstring · nullableRead-onlyOptional

phone_numberstring · nullableRead-onlyOptional

resolvedbooleanOptional

Whether this chat is considered resolved by the assigned agent. Can automatically be set to false if contact keeps sending messages.

Responses

200Success

application/json

wa_idstringRead-onlyRequired

WhatsApp ID — either a phone number in canonical form (e.g. 48123123123) or a Business-Scoped User ID (e.g. US.13491208655302741918) for users who have hidden their phone number.

bsuidstring · nullableRead-onlyRequired

phone_numberstring · nullableRead-onlyRequired

resolvedbooleanOptional

Whether this chat is considered resolved by the assigned agent. Can automatically be set to false if contact keeps sending messages.

patch/api/v1/chats/{wa_id}/resolve/

PATCH /api/v1/chats/{wa_id}/resolve/ HTTP/1.1
Host: your-stack.inbox.getchat.360dialog.io/
Authorization: Token YOUR_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "resolved": true
}

200Success

{
  "wa_id": "text",
  "bsuid": "text",
  "phone_number": "text",
  "resolved": true
}

get

Singleton resource served at /settings/useravailability/ (no pk).

Authorizations

AuthorizationstringRequired

Responses

200Success

application/json

feature_set_enabledbooleanOptional

Only if checked, any settings in this feature set take effect. If not checked, auto-assignment will not happen, and user availability has no effect (and cannot be toggled by users)

get/api/v1/settings/useravailability/

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

200Success

{
  "feature_set_enabled": true
}

put

Singleton resource served at /settings/useravailability/ (no pk).

Authorizations

AuthorizationstringRequired

Body

feature_set_enabledbooleanOptional

Only if checked, any settings in this feature set take effect. If not checked, auto-assignment will not happen, and user availability has no effect (and cannot be toggled by users)

Responses

200Success

application/json

feature_set_enabledbooleanOptional

Only if checked, any settings in this feature set take effect. If not checked, auto-assignment will not happen, and user availability has no effect (and cannot be toggled by users)

put/api/v1/settings/useravailability/

PUT /api/v1/settings/useravailability/ HTTP/1.1
Host: your-stack.inbox.getchat.360dialog.io/
Authorization: Token YOUR_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "feature_set_enabled": true
}

200Success

{
  "feature_set_enabled": true
}

patch

Singleton resource served at /settings/useravailability/ (no pk).

Authorizations

AuthorizationstringRequired

Body

feature_set_enabledbooleanOptional

Only if checked, any settings in this feature set take effect. If not checked, auto-assignment will not happen, and user availability has no effect (and cannot be toggled by users)

Responses

200Success

application/json

feature_set_enabledbooleanOptional

Only if checked, any settings in this feature set take effect. If not checked, auto-assignment will not happen, and user availability has no effect (and cannot be toggled by users)

patch/api/v1/settings/useravailability/

PATCH /api/v1/settings/useravailability/ HTTP/1.1
Host: your-stack.inbox.getchat.360dialog.io/
Authorization: Token YOUR_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "feature_set_enabled": true
}

200Success

{
  "feature_set_enabled": true
}

PreviousContacts

NextTags

Last updated 5 days ago

Was this helpful?