API docs by Redocly

(0.0.0)

Download OpenAPI specification:Download

Authorization

Endpoints related to Authorization

convertIdToken

Converts the Refresh Token to Auth Token.

DEPRECATED: In previous versions, this endpoint converted the ID Token to Auth Token. If you use this endpoint now, it will convert the Refresh Token to Auth Token.

You should migrate to convertRefreshToken method now, before convertIdToken is removed in future versions.

The Refresh Token is acquired during password-less authentication flow, or by a related inbox User via API: retrieveRefreshToken and can be used to authenticate Inbox User without password.

Refresh Token will be reset each time when it is converted to Auth Token.

Note that new Auth Token is created only if it does not exist (if there were no logins in the past, for this user). If the Auth Token already exists, it is returned here, and new Auth Token is not created.

For more information about Auth Token, see Token authorization.

Request Body schema:
id_token
required
string

Refresh Token acquired from retrieveRefreshToken endpoint.

Responses

Request samples

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

Response samples

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

convertRefreshToken

Converts the Refresh Token to Auth Token.

The Refresh Token is acquired during password-less authentication flow, or by a related inbox User via API: retrieveRefreshToken and can be used to authenticate Inbox User without password.

Note that new Auth Token is created only if it does not exist (if there were no logins in the past, for this user). If the Auth Token already exists, it is returned here, and new Auth Token is not created.

For more information about Auth Token, see Token authorization.

Request Body schema:
refresh_token
required
string

Refresh Token acquired from retrieveRefreshToken endpoint.

keep_refresh_token
boolean
Default: false

Keep Refresh Token unchanged in the API. By default (false), Refresh Token will be reset each time when it is converted to Auth Token.

Responses

Request samples

Content type
{
  • "refresh_token": "string",
  • "keep_refresh_token": false
}

Response samples

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

createAuthToken

Creates the Auth Token for provided username and password.

Note that new Auth Token is created only if it does not exist (if there were no logins in the past, for this user). If the Auth Token already exists, it is returned here, and new Auth Token is not created.

See Token authorization,

Request Body schema:
username
required
string
password
required
string

Responses

Request samples

Content type
No sample

Response samples

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

WhatsApp Accounts

WhatsApp Accounts of your inbox

Messages

You can receive and send WhatsApp messages using following endpoints.

Persons

WhatsApp Users who contacted your Inbox

Contacts

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.

Chats

Existing conversations with WhatsApp Users

createChatImport

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:
tokenAuthcookieAuthNone
Request Body schema:
chat_text
required
string

The text chat log as given to you by WhatsApp

Array of objects (ChatImportContact)

Required if chat partner is in the device's contacts, supply chat partner's phone number with this. If you cannot tell which contact is incoming and which is outgoing, supply both. Do not supply more than two contacts.

utc_offset_minutes
required
integer

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_code
required
string

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

required
Array of objects (ChatImportMediaFile)

Responses

Request samples

Content type
{
  • "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": [
    ],
  • "utc_offset_minutes": -420,
  • "device_language_code": "en-US",
  • "media_files": [
    ]
}

Response samples

Content type
application/json
{
  • "contact": {
    },
  • "new_messages": 0,
  • "wa_id": "string",
  • "last_message": {
    },
  • "assigned_to_user": {
    },
  • "assigned_group": {
    },
  • "tags": [
    ]
}

Tags

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

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

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

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

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

Assignment

You can assign Chats to Users or Groups.

Saved Responses

You can keep simple text Saved Responses that your Inbox Users can use separately from Templates

Templates

Message Templates management proxy

Business Profile

Your WhatsApp Business Profile

Media Files

JavaScript multipart/form-data Example To Create A Media File:

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

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

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

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

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

<binary data here>

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

retrieveMediaFile

Retrieve binary raw media file

Used in media messages and for display.

Authorizations:
tokenAuthcookieAuth
path Parameters
id
required
string <uuid>

A UUID string identifying this media file.

query Parameters
id
required
string

A UUID string identifying this media file.

mime_type_subtype
string

mime_type_type and mime_type_subtype that, when combined together, determine for you a content type of retrieved media file - {mime_type_type}/{mime_type_subtype}. For example mime_type_type=image&mime_type_subtype=jpeg means Content-Type image/jpeg. This information is not needed for HTTP client that will ignore file type (for example most of web browsers during file download) but it will be crucial for others (for example web browsers during file display or WhatsApp displaying outgoing message media to end users)

mime_type_type
string

mime_type_type and mime_type_subtype that, when combined together, determine for you a content type of retrieved media file: {mime_type_type}/{mime_type_subtype}. For example mime_type_type=image&mime_type_subtype=jpeg means Content-Type image/jpeg. This information is not needed for HTTP client that will ignore file type (for example most of web browsers during file download) but it will be crucial for others (for example web browsers during file display or WhatsApp displaying outgoing message media to end users)

Responses

Users

Inbox Users

Groups

Groups of Inbox Users

E-mail Notifications

Send e-mail notifications

resendActivationEmail

Resend activation mail

Re-try activation e-mail in case something gone wrong (e-mail inbox full, incorrect e-mail address that is now changed, etc.).

Authorizations:
tokenAuthcookieAuthNone

Responses

Response samples

Content type
application/json
{ }

Webhooks

These API endpoints allow you to manage Webhooks.

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

Status

These API endpoints allow you to check the statuses of your Inbox and installed Plugins.

listHealthStatuses

Check the health status(es) of your inbox

Authorizations:
tokenAuthcookieAuthNone

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Errors

These API endpoints allow you to check the errors received from WABA

Audit Logs

This API endpoint allows you to list logs of various events such as chats being assigned or resolved

Firebase CM device tokens

Manages your mobile device's Firebase Cloud Messaging token. This allows you to receive push notifications upon receiving messages, even if the app is in the background.

Note that every Token submitted using this API is associated to the authenticated User. You can only register, list, update and deregister Tokens owned by your User (currently authenticated User).

In order to get your Firebase token from Google in the first place, you need to send a request to Firebase using one of its client libraries while holding the public Firebase certificate of this service.

The inbox then also needs this token. The workflow is similar to other REST operations with one big exception, that you need to account for. After registration, the token has to be re-registered on a regular basis; once per month is recommended by Firebase itself. Re-registration is done using the same API endpoint that allows initial registration.

In case your app user logs out of the Inbox, please delete the FCM token that was in use by that device using the DELETE endpoint.