{ "openapi": "3.0.3", "info": { "title": "360dialog Inbox API", "version": "1.28.0", "description": "REST API over the 360dialog Inbox: chats, messages, assignment, tags, contacts, templates, media, users and webhooks. Guides and concepts are in the Inbox API section of the 360dialog client documentation." }, "paths": { "/api/v1/audit_logs/": { "get": { "operationId": "retrieveAuditLogs", "description": "Returns one day of audit logs, ordered by timestamp, newest first, with links to next or previous page (unless there is no more data for this day, in which case these URLs are null; in particular, it is even null if the next/previous day has logs). The format of `data` varies depending on the event type.", "parameters": [ { "in": "query", "name": "day_start_timestamp", "schema": { "type": "integer" }, "description": "Unix timestamp, in UTC, of the first minute of the day whose logs should be fetched. Defaults to the current day (starting 00:00 UTC). Note that logs are ordered descendingly by timestamp nonetheless, meaning that the first result is the log closest to the last minute of that day. Supports time zones in the sense that this parameter does not have to be 00:00 in UTC (i.e. while the timestamp has to be in UTC, it is not required to be 00:00 in UTC)." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "How many log entries to return at maximum. Defaults to no limit. Note that log entries from other days are not returned, even if the specified day's results count to less than limit." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "How many log entries to skip before listing. Defaults to 0." } ], "tags": [ "Audit Logs" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {}, "description": "Unspecified response body" } } }, "description": "" } } } }, "/api/v1/auth/token/": { "post": { "operationId": "createAuthToken", "description": "Returns the token for a username and password. If the user already has a token, the same one is returned. Send it on every other request as `Authorization: Token `.", "tags": [ "Authorization" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AuthToken" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthToken" } } }, "description": "" } }, "security": [] } }, "/api/v1/chat_assignment/{wa_id}/": { "get": { "operationId": "retrieveChatAssignment", "description": "Get who a Chat is assigned to: a User, a Group, or nobody.", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Assignment" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAssignment" } } }, "description": "" } } }, "put": { "operationId": "updateChatAssignment", "description": "Assign a Chat to yourself or any User or Group\n\nYou can remove Chat assignment by passing `null` value.", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Assignment" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAssignment" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ChatAssignment" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ChatAssignment" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAssignment" } } }, "description": "" } } }, "patch": { "operationId": "partialUpdateChatAssignment", "description": "Assign a Chat to yourself or any User or Group\n\nYou can remove Chat assignment by passing `null` value.", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Assignment" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedChatAssignment" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedChatAssignment" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedChatAssignment" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAssignment" } } }, "description": "" } } } }, "/api/v1/chat_assignment/{wa_id}/auto-assignment/": { "post": { "operationId": "autoAssignment", "description": "Assign a Chat to an automatically selected User", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Assignment" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAutoAssignment" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ChatAutoAssignment" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ChatAutoAssignment" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAutoAssignment" } } }, "description": "" } } } }, "/api/v1/chat_assignment_events/": { "get": { "operationId": "listChatAssignmentEvents", "description": "List all Chat assignment events for selected Chat", "parameters": [ { "in": "query", "name": "before_time", "schema": { "type": "integer" }, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only events that are **older** than specified `before_time`.\n\n\nThis should be used when implementing scroll of the event view from newest to oldest." }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } }, { "in": "query", "name": "since_time", "schema": { "type": "integer" }, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only events that are **at the same timestamp or newer** than specified `since_time`.\n Note that, as opposed to `before_time` param, this param returns messages where timestamp is equal\n to the given value.\n\n\nThis should be used when implementing scroll of the event view from oldest to newest." }, { "in": "query", "name": "wa_id", "schema": { "type": "string" }, "description": "WhatsApp ID of related Chat" } ], "tags": [ "Assignment" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedChatAssignmentEventList" } } }, "description": "" } } } }, "/api/v1/chat_import/": { "post": { "operationId": "createChatImport", "description": "Import an existing WhatsApp chat generated by the \"Export chat\" action in the WhatsApp Business app.\n\nUse this endpoint to upload the chat and all media files. Requires some preparation work to be done in the app\n that served as export target for WhatApp.\n\nParameters you supply such as contacts, UTC offset must come from the device you exported the WhatsApp chat on.", "tags": [ "Chats" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatImportRequest" }, "examples": { "Text": { "value": { "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" } ] }, "summary": "text" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ChatImportRequest" }, "examples": { "Text": { "value": { "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" } ] }, "summary": "text" } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ChatImportRequest" }, "examples": { "Text": { "value": { "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" } ] }, "summary": "text" } } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Chat" } } }, "description": "" } } } }, "/api/v1/chat_tagging/": { "post": { "operationId": "createChatTagging", "description": "Assign a Tag to selected Chat.\n\nYou cannot create the same Chat + Tag Tagging pair twice, however you can delete and create the same pair again.", "tags": [ "Tags" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTagging" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ChatTagging" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ChatTagging" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTagging" } } }, "description": "" } } } }, "/api/v1/chat_tagging/{id}/": { "get": { "operationId": "retrieveChatTagging", "description": "Get a single Chat Tagging.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this chat tagging.", "required": true } ], "tags": [ "Tags" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTagging" } } }, "description": "" } } }, "delete": { "operationId": "destroyChatTagging", "description": "Remove a Tag from a Chat by deleting the Chat Tagging.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this chat tagging.", "required": true } ], "tags": [ "Tags" ], "responses": { "204": { "description": "No response body" } } } }, "/api/v1/chat_tagging_events/": { "get": { "operationId": "listChatTaggingEvents", "description": "List all Chat tagging events for selected Chat", "parameters": [ { "in": "query", "name": "before_time", "schema": { "type": "integer" }, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only events that are **older** than specified `before_time`.\n\n\nThis should be used when implementing scroll of the event view from newest to oldest." }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } }, { "in": "query", "name": "since_time", "schema": { "type": "integer" }, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only events that are **at the same timestamp or newer** than specified `since_time`.\n Note that, as opposed to `before_time` param, this param returns messages where timestamp is equal\n to the given value.\n\n\nThis should be used when implementing scroll of the event view from oldest to newest." }, { "in": "query", "name": "wa_id", "schema": { "type": "string" }, "description": "WhatsApp ID of related Chat" } ], "tags": [ "Tags" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedChatTaggingEventList" } } }, "description": "" } } } }, "/api/v1/chats/": { "get": { "operationId": "listChats", "description": "Get existing chats and the number of new messages in each chat.\n\nThis endpoint is similar to `/persons/` endpoint - here also contacts are listed, but only these contacts for which conversation already exists.\n\n\nChats are sorted by `last_message_timestamp`, newest to oldest.\n\n\nTo mark these messages as received, first store `wa_id` (WhatsApp ID) field value of this endpoint.\nThen use `messages` endpoint to read messages for related contact and\nstore the message `id`. After making sure the user has received the message on the frontend,\ncheck the timestamp of the most recent message received and use it with\n`/mark_as_received/` endpoint to actually mark it as received.\n\n\nMarking messages as received is important to prevent duplicate notifications.\n\nResponse is paginated.\nUse `limit` and `offset` query parameters to access each page.\nQuery parameter `limit` default value is 100.\nJSON response body field `count` tells the total number of elements available on all pages.", "parameters": [ { "in": "query", "name": "assigned_group", "schema": { "type": "integer" }, "description": "Filter only Chats assigned to specified Group.\n Skip this param to display all messages currently logged in User has access to.\n Param value is an integer identifier of the Group.\n Only Groups the User is member of can be used." }, { "in": "query", "name": "assigned_to_me", "schema": { "type": "boolean" }, "description": "Filter only Chats assigned to currently logged in User.\n Skip this param or leave default `false` to display all messages User has access to." }, { "in": "query", "name": "blocked", "schema": { "type": "boolean" }, "description": "Filter only Chats which are blocked due to spam and abuse of WhatsApp." }, { "in": "query", "name": "chat_tag_id", "schema": { "type": "integer" }, "description": "Filter only Chats having given tag ID." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Number of results to return per page." }, { "in": "query", "name": "message_has_referral", "schema": { "type": "boolean" }, "description": "When set to `true`, only Chats having Message with referral object are returned." }, { "in": "query", "name": "message_referral_body", "schema": { "type": "string" }, "description": "Filter only Chats that had a Message with `referral.body`, and the **last such Message** had `referral.body` equal to given param." }, { "in": "query", "name": "message_referral_headline", "schema": { "type": "string" }, "description": "Filter only Chats that had a Message with `referral.headline`, and the **last such Message** had `referral.headline` equal to given param." }, { "in": "query", "name": "message_referral_media_type", "schema": { "type": "string" }, "description": "Filter only Chats that had a Message with `referral.media_type`, and the **last such Message** had `referral.media_type` equal to given param.\n Possible values are `\"image\"` and `\"video\"`." }, { "in": "query", "name": "message_referral_source_id", "schema": { "type": "string" }, "description": "Filter only Chats that had a Message with `referral.source_id`, and the **last such Message** had `referral.source_id` equal to given param." }, { "in": "query", "name": "message_referral_source_type", "schema": { "type": "string" }, "description": "Filter only Chats that had a Message with `referral.source_type`, and the **last such Message** had `referral.source_type` equal to given param.\n Possible values are `\"ad\"` and `\"post\"`." }, { "in": "query", "name": "message_referral_source_url", "schema": { "type": "string" }, "description": "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`.\n For example, `message_referral_source_url=asd` matches `referral.source_url` = `https://asd.com`" }, { "in": "query", "name": "messages_before_time", "schema": { "type": "integer" }, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only Chats **containing Messages** that are **older** than specified value." }, { "in": "query", "name": "messages_since_time", "schema": { "type": "integer" }, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only Chats **containing Messages** at **the same timestamp or newer** than specified value." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "The initial index from which to return the results." }, { "in": "query", "name": "reported", "schema": { "type": "boolean" }, "description": "Filter only Chats which are reported due to spam and abuse of WhatsApp." }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Filter Chats by string query - search for chats containing specified text phrase.\n\nThe API will search in following places:\n\n* `contact.waba_payload.profile.name` and `contact.waba_payload.wa_id` of each Chat\n\n* `name` field of each Tag in `tags` of each Chat" }, { "in": "query", "name": "unread", "schema": { "type": "boolean" }, "description": "Filter only Chats that have unread messages." } ], "tags": [ "Chats" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedChatList" } } }, "description": "" } } } }, "/api/v1/chats/{wa_id}/": { "get": { "operationId": "retrieveChat", "description": "Get one Chat, including its contact, the number of new messages, its assignment and its tags.", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Chats" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Chat" } } }, "description": "" } } } }, "/api/v1/chats/{wa_id}/handover/": { "post": { "operationId": "handoverChat", "description": "Hands control of this conversation back to Meta Business Agent.\n\nThe reverse direction needs no endpoint: the inbox takes control of a\nconversation simply by sending a message to it.", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Chats" ], "responses": { "200": { "description": "Thread control passed to the Inbox", "content": { "application/json": { "schema": { "type": "object", "properties": { "thread_controller": { "type": "string", "example": "mba" } } }, "example": { "thread_controller": "mba" } } } } } } }, "/api/v1/chats/{wa_id}/resolve/": { "patch": { "operationId": "updateResolved", "description": "Marks a chat as resolved, or removes this mark.", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Chats" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedResolvedChat" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedResolvedChat" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedResolvedChat" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedChat" } } }, "description": "" } } } }, "/api/v1/contacts/": { "get": { "operationId": "listContacts", "description": "List contacts. Use `search` to filter by name or WhatsApp ID.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Number of results to return per page." }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Filter Contacts by string query.\n\n\nSearching is expensive, so when implementing this functionality on the frontend,\nmake sure the user really finished typing the search query before calling this endpoint." } ], "tags": [ "Contacts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedContactModelList" } } }, "description": "" } } } }, "/api/v1/contacts/{wa_id}/": { "get": { "operationId": "contactDetails", "description": "Retrieves Contact details. You should try to use this endpoint as little as possible, for example:\n\n* when a detailed view of one Person is displayed", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Contacts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } }, "description": "" } } } }, "/api/v1/contacts/{wa_id}/block/": { "post": { "operationId": "blockContact", "description": "Block contacts due to spam and abuse of WhatsApp. To block a contact they had to have sent you a message in the last 24 hours.", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Contacts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBlock" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ContactBlock" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ContactBlock" } } } }, "responses": { "200": { "description": "No response body" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsBlockOrReport400Response" }, "examples": { "ContactNotEngagedWithYouInTheLast24Hrs": { "value": { "meta": { "api_status": "stable", "version": "2.45.1" }, "errors": [ { "code": 2048, "title": "Not engaged contact", "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs." } ] }, "summary": "Contact hasn't engaged with you in the last 24 hrs" } } } }, "description": "User error. Please check your request and API response." } } } }, "/api/v1/contacts/{wa_id}/report/": { "post": { "operationId": "reportContact", "description": "Report contacts due to spam and abuse of WhatsApp. Before reporting a contact, they had to have sent you a message in the last 24 hours.", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Contacts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactReport" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ContactReport" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ContactReport" } } } }, "responses": { "200": { "description": "No response body" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsBlockOrReport400Response" }, "examples": { "ContactNotEngagedWithYouInTheLast24Hrs": { "value": { "meta": { "api_status": "stable", "version": "2.45.1" }, "errors": [ { "code": 2048, "title": "Not engaged contact", "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs." } ] }, "summary": "Contact hasn't engaged with you in the last 24 hrs" } } } }, "description": "" } } } }, "/api/v1/contacts/{wa_id}/unblock/": { "post": { "operationId": "unblockContact", "description": "Unblock contacts which were blocked or reported to block previously.", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Contacts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBlock" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ContactBlock" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ContactBlock" } } } }, "responses": { "200": { "description": "No response body" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsBlockOrReport400Response" }, "examples": { "InvalidWhatsAppID": { "value": { "meta": { "api_status": "stable", "version": "2.45.1" }, "errors": [ { "code": 1009, "title": "Parameter value is not valid", "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code" } ] }, "summary": " WhatsApp ID is not valid" } } } }, "description": "User error. Please check your request and API response." } } } }, "/api/v1/contacts/blocklist/": { "get": { "operationId": "listBlockedContacts", "description": "View blocked contacts list. These phone numbers are blocked by the user due to spam and abuse of WhatsApp.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Number of results to return per page." }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "The initial index from which to return the results." } ], "tags": [ "Contacts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsBlockListResponse" }, "examples": { "Text": { "value": { "contacts": [ { "wa_id": "16315551000@s.whatsapp.net" } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } }, "summary": "Type `text`" } } } }, "description": "" } } } }, "/api/v1/errors/waba/": { "get": { "operationId": "listWabaErrors", "description": "List errors reported by WhatsApp for your number.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "Errors" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedWabaErrorList" } } }, "description": "" } } } }, "/api/v1/errors/waba/{id}/": { "get": { "operationId": "retrieveWabaError", "description": "Get a single error reported by WhatsApp.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this WABA error.", "required": true } ], "tags": [ "Errors" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WabaError" } } }, "description": "" } } } }, "/api/v1/groups/": { "get": { "operationId": "listGroups", "description": "List the Groups in your Inbox.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "Groups" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedGroupList" } } }, "description": "" } } } }, "/api/v1/groups/{id}/": { "get": { "operationId": "retrieveGroup", "description": "Get a single Group.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this user group.", "required": true } ], "tags": [ "Groups" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } }, "description": "" } } } }, "/api/v1/mark_as_received/": { "post": { "operationId": "createReceivedMessageMark", "description": "Create a new mark, marking messages as received.\n\nEvery new message will be provided via `/chats/` endpoint.\nIn order to no longer receive these messages via above endpoint, you need to mark them as received.\n\n\nYou can parse `/messages/` endpoint object field `received`\nto determine if a given message still needs to be marked as received.\nBy POSTing data to this endpoint, you create (or update) a mark of `timestamp` in relation to a conversation\nwith a contact of given `customer_wa_id`.\n\n### Recommended usage\n\nIt is recommended to\n* use WABA Webhooks\n* or to POST to this endpoint whenever you receive a batch of messages using\n`/messages/` endpoint **and** you confirmed the message was received by the user.\n\n### Forwarding messages to your system\n\nIf you develop some kind of integration of data between systems or simply bridge these messages to other systems,\nreceived message mark is useful for determining which Chats have new messages.\nBy using `/chats/` endpoint you can quickly determine which contacts\nhave new, unreceived messages. But to keep this endpoint up to date, you need to create received message marks.\n\n### Instant mark\n\nMessages propagated to a User via WABA Webhook successfully (200 OK status code)\nare automatically marked as received by related User.\n\nIt is also possible to mark messages as received \"instantly\" when polling them via our API directly.\nIn such case you should use `mark_as_received` parameter of `/messages/` endpoint.\n\nIf you use mentioned `mark_as_received` parameter or you\nconfigured a WABA Webhook,\nusage of the `/mark_as_received/` endpoint described here is no longer needed.", "tags": [ "Messages" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedMessageMark" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ReceivedMessageMark" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ReceivedMessageMark" } } }, "required": true }, "responses": { "200": { "description": "No response body" }, "452": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAsReceivedMessage452Response" }, "examples": { "452": { "value": { "reason": "Field timestamp value is too far in the future.\n\n This API cannot mark messages as received for timestamps that are in the future.\n The message must be first stored in the Inbox in order to mark it as received in the Inbox\n and then mark as read in WhatsApp.\n Make sure to not use current timestamp from your local clock as it might be off with the Inbox server clock.\n The best idea is to use only timestamps from incoming message payload.\n Only then you can avoid race conditions of marking messages as received while not (yet) receiving them.", "timestamp": 1230796536, "server_timestamp": 1230796535 } } } } }, "description": "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." }, "453": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAsReceivedMessage453Response" }, "examples": { "453": { "value": { "reason": "Contact of given customer_wa_id does not exist" } } } } }, "description": "Contact of given customer_wa_id does not exist" } } } }, "/api/v1/media/": { "post": { "operationId": "createMediaFile", "description": "Create a new media file\n\nUse this endpoint to upload a new media file **before** you enter it into a new message as an attachment.", "tags": [ "Media Files" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MediaCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMedia" } } }, "description": "" } } } }, "/api/v1/media/{id}/": { "get": { "operationId": "retrieveMediaFile", "description": "Retrieve binary raw media file\n\nUsed in media messages and for display.\n\n- Owned media (uploaded via this Inbox, identified by a UUID) is\n served as a 302 redirect to a short-lived signed URL on Google\n Cloud Storage, so the bucket can stay private and bytes never\n flow through the Inbox pod.\n- Inbound media hosted by WABA (numeric IDs) is proxied through\n WABA-Stack as before.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this media file.", "required": true }, { "in": "query", "name": "mime_type_subtype", "schema": { "type": "string" }, "description": "`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)" }, { "in": "query", "name": "mime_type_type", "schema": { "type": "string" }, "description": "`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)" } ], "tags": [ "Media Files" ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "video/3gpp": { "schema": { "type": "string", "format": "binary" } }, "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/mp4": { "schema": { "type": "string", "format": "binary" } }, "audio/amr": { "schema": { "type": "string", "format": "binary" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/ogg; codecs=opus": { "schema": { "type": "string", "format": "binary" } } }, "description": "" }, "302": { "description": "Owned media (UUID). Redirects to a short-lived signed URL on Google Cloud Storage; clients should follow the redirect to download the bytes." }, "404": { "description": "There is no such file, or the file was deleted (e.g. expired at WhatsApp)." }, "429": { "description": "Media downloads are temporarily rate limited upstream. Retry after the number of seconds in the Retry-After header." }, "503": { "description": "Media file is temporarily unavailable due to an upstream error. Retry later." } } } }, "/api/v1/message_tagging/": { "post": { "operationId": "createMessageTagging", "description": "Assign a Tag to selected Message.\n\nNote that by tagging a Message, corresponding Chat is tagged\nautomatically with the same tag.\n\n\nYou cannot create the same Message + Tag Tagging pair twice,\nhowever you can delete and create the same pair again.", "tags": [ "Tags" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageTagging" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/MessageTagging" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MessageTagging" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageTagging" } } }, "description": "" } } } }, "/api/v1/message_tagging/{id}/": { "get": { "operationId": "retrieveMessageTagging", "description": "Get a single Message Tagging.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this message tagging.", "required": true } ], "tags": [ "Tags" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageTagging" } } }, "description": "" } } }, "delete": { "operationId": "destroyMessageTagging", "description": "Remove a Tag from a Message by deleting the Message Tagging.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this message tagging.", "required": true } ], "tags": [ "Tags" ], "responses": { "204": { "description": "No response body" } } } }, "/api/v1/message_tagging_events/": { "get": { "operationId": "listMessageTaggingEvents", "description": "List all Message tagging events for selected Chat or Message", "parameters": [ { "in": "query", "name": "before_time", "schema": { "type": "integer" }, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only events that are **older** than specified `before_time`.\n\n\nThis should be used when implementing scroll of the event view from newest to oldest." }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "in": "query", "name": "message_id", "schema": { "type": "string" }, "description": "Message ID" }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } }, { "in": "query", "name": "since_time", "schema": { "type": "integer" }, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only events that are **at the same timestamp or newer** than specified `since_time`.\n Note that, as opposed to `before_time` param, this param returns messages where timestamp is equal\n to the given value.\n\n\nThis should be used when implementing scroll of the event view from oldest to newest." }, { "in": "query", "name": "wa_id", "schema": { "type": "string" }, "description": "WhatsApp ID of related Chat" } ], "tags": [ "Tags" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedMessageTaggingEventList" } } }, "description": "" } } } }, "/api/v1/messages/": { "get": { "operationId": "listMessages", "description": "A wrapper of `messages` object of\n[Inbound Notifications from WhatsApp Business API](https://developers.facebook.com/docs/whatsapp/api/webhooks/inbound)\n(WhatsApp).\n\nThis object field `waba_payload` contains exactly the same data as specified in WhatsApp Business API.\n\nThis endpoint is useful for loading messages into a view. Example use cases:\n\n* Message view is loaded for the first time\n* Contact message history is loaded or is scrolled\n\nTo get the number of new messages for all contacts, see `chats` endpoint.\n\nMessages are ordered from newest to oldest.\n\n### Recommended usage\n\nYou can use `limit` and `offset` query parameters to access each page, but it is often advised to use `before_time`\ninstead of `offset`.\n\nFor example, if you only need to get most recent 20 messages, you will use:\n\n```\n/api/v1/messages/?limit=20\n```\n\nBut if you need to read the history of 20 messages before, you should use `before_time` equal to the timestamp\nof the last (20th) message you got before:\n\n```\n/api/v1/messages/?limit=20&before_time=1234567890\n```\n\nAs a result, you will get up to 20 messages that were sent before previous 20 messages.\n\nUsing `before_time` instead of `offset` is advised because it is possible you will get new messages when you browse\nyour paginated history of messages. Since messages are ordered from newest to oldest, `offset` based pagination\nis changing each time you receive a new message from a contact. Using `before_time` solves this problem.", "parameters": [ { "in": "query", "name": "assigned_group", "schema": { "type": "integer" }, "description": "Filter only Messages of Chats assigned to specified Group.\n Skip this param to display all messages currently logged in User has access to.\n Param value is an integer identifier of the Group.\n Only Groups the User is member of can be used." }, { "in": "query", "name": "assigned_to_me", "schema": { "type": "boolean" }, "description": "Filter only Messages of Chats assigned to currently logged in User.\n Skip this param or leave default `false` to display all messages User has access to." }, { "in": "query", "name": "before_time", "schema": { "type": "integer" }, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only messages that are **older** than specified `before_time`.\n This parameter makes it easy to just pass the timestamp of the last message you have\n and receive only messages older than related message.\n\n\nThis should be used when implementing scroll of the messages from newest to oldest." }, { "in": "query", "name": "chat_tag_id", "schema": { "type": "integer" }, "description": "Filter only Messages of Chats having given tag ID." }, { "in": "query", "name": "from_us", "schema": { "type": "boolean" }, "description": "Filter only Messages that are either from us (inbox users and automation) or not." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Number of results to return per page." }, { "in": "query", "name": "mark_as_received", "schema": { "type": "integer" }, "description": "Mark all returned messages as received by you (logged in user). You need to use either this param or POST to\n `/mark_as_received/` endpoint to mark messages as received.\n Marking messages as received by you is needed to generate a proper list of new messages.\n (You can check how many unread messages there are for each contact with\n `/chats/` endpoint.)\n It is required to use one or the other when you implement any kind of indication of new/unread messages\n or when you simply forward messages to your system in batches and would like to receive only\n fresh messages on each iteration.\n " }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "The initial index from which to return the results." }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Filter Messages by string query - search for messages containing specified text phrase.\n\n\nThe API will search in following places:\n\n* `text.body` field of `waba_payload` JSON\n\n* `{media_type}.caption` or `{media_type}.filename` of media type message fields:\n `image`, `document`, `audio`, `video` ,`voice`, `sticker`\"\n\n* `name` field of each Tag in `tags` field of each Message" }, { "in": "query", "name": "since_time", "schema": { "type": "integer" }, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only messages that are **at the same timestamp or newer** than specified `since_time`.\n\n\nThis should be used when implementing scroll of the messages from oldest to newest." }, { "in": "query", "name": "wa_id", "schema": { "type": "string" }, "description": "WhatsApp id of related contact" } ], "tags": [ "Messages" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedRetrieveMessageList" }, "examples": { "Text": { "value": { "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" } } } ] } ] }, "summary": "Type `text`" }, "Image": { "value": { "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": { "from": "4812312313", "id": "ABGGSFEBeRJ_AhAJinj0ofZtfrtT2WvSGfcc", "type": "image", "image": { "caption": "Here is the picture of the fridge. Thanks!", "id": "d3c4c624-f53b-883d-4d7b-688832ad1234", "mime_type": "image/jpeg", "sha256": "061ea17d56ad7ee9384da7526411b7309a9b080a264fdbb32786028f9ec1f606" }, "timestamp": "1611310767" }, "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" } } } ] } ] }, "summary": "Type `image`" } } } }, "description": "" }, "452": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "examples": { "425": { "value": { "reason": "Contact of given wa_id does not exist" } } } } }, "description": "The contact does not exist" } } }, "post": { "operationId": "createMessage", "description": "Create a new message\n\nThis object contains selected data that is following specification of\n[WhatsApp Business API](https://developers.facebook.com/docs/whatsapp/api/messages).\n\nThe `type` field determines the type of message. Choosing one of possible types makes related field required.\nFor example, choosing `\"type\": \"text\"` makes field `text` required.\n\nIf the recipient does not have WhatsApp, the resulting WhatsApp Business API error (WhatsApp Business API Client\nError Code 470) will be forwarded to you asynchronously using another channel (e.g. websocket).", "tags": [ "Messages" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessage" }, "examples": { "Text": { "value": { "wa_id": "48123123123", "type": "text", "text": { "body": "Hello!" } }, "summary": "Type `text`" }, "Image": { "value": { "wa_id": "48123123123", "type": "image", "image": { "link": "https://baseurl/api/v1/media/image.jpg", "caption": "Here is the picture of the fridge. Thanks!" } }, "summary": "Type `image`" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CreateMessage" }, "examples": { "Text": { "value": { "wa_id": "48123123123", "type": "text", "text": { "body": "Hello!" } }, "summary": "Type `text`" }, "Image": { "value": { "wa_id": "48123123123", "type": "image", "image": { "link": "https://baseurl/api/v1/media/image.jpg", "caption": "Here is the picture of the fridge. Thanks!" } }, "summary": "Type `image`" } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateMessage" }, "examples": { "Text": { "value": { "wa_id": "48123123123", "type": "text", "text": { "body": "Hello!" } }, "summary": "Type `text`" }, "Image": { "value": { "wa_id": "48123123123", "type": "image", "image": { "link": "https://baseurl/api/v1/media/image.jpg", "caption": "Here is the picture of the fridge. Thanks!" } }, "summary": "Type `image`" } } } }, "required": true }, "responses": { "200": { "description": "Message sent.\n\n> **DEPRECATED:** This endpoint either replies with **202** status code or other documented codes." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageSendSuccessfulResponse" }, "examples": { "Queue": { "value": { "reason": "Message is saved and will be sent as soon as other messages currently pending for this user are delivered.", "id": "8b176ba5-fa8e-458e-94ad-85d1ae8f3be0" }, "summary": "Message added to queue" } } } }, "description": "Message is added to the queue and will be sent soon.\n\n> Note that **this doesn't indicate that the message is sent**.\nAwait message \"statuses\" events\nto determine when message is sent, received and read by recipient.\nNote that you need to inspect `\"getchat_id\"` value inside received `\"statuses\"` events,\nin order to be able to relate statuses with outgoing messages." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageWabaErrorResponse" }, "examples": { "FieldsMissing": { "value": { "type": [ "This field may not be null." ], "wa_id": [ "This field may not be blank." ] }, "summary": "Fields missing in request payload" }, "JsonDataInvalid/missing": { "value": { "reason": "JSON data not provided" }, "summary": "JSON data not provided" } } } }, "description": "User error. Please check your request and API response.\n\n> There are various scenarios for 400 status code and the API reply will provide as precise information\non the client-side error as possible. For example, if JSON data is not provided, `\"reason\"` field\nis returned with `\"JSON data not provided\"` as reason value.\nIf there are problems with specific fields, those are denoted with their names in the API response\npayload. Every field can have multiple errors, so those error messages are provided in a list\n(see 400 response examples)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageWabaErrorResponse" }, "examples": { "403": { "value": { "reason": "You have no permission to send messages to this Chat." } } } } }, "description": "You have no permission to send messages to this Chat.\n\n> Check your User account settings. Each User needs to have `permissions` specified -\nif the User can read from or write to Chats." }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageWabaErrorResponse" }, "examples": { "423": { "value": { "reason": "Queue is full. Your quota is full of pending messages." } } } } }, "description": "Queue is full. Your quota is full of pending messages.\n\n> Your quota is limited (by default) to 1.5M messages stored permanently.\nWhen you reach your quota, the oldest messages in your storage are removed when they are over quota.\nYou can reach your quota by either receiving or sending messages.\nWhen sending, messages are first added to the queue and then they are propagated to WhatsApp.\nIf you are too fast, you might end up with entire quota (by default 1.5 million) of messages\nconsisting of pending messages. This leads to a situation when you no longer can add messages to the\nqueue, because it would remove not-yet-sent messages from your storage.\nNormally, this condition is hard to be met, but can be met easily if your WhatsApp Business API\nendpoint has been blocked by Meta for some reason, or the endpoint has some performance issues." }, "453": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageWabaErrorResponse" }, "examples": { "453": { "value": { "reason": "Customer care messaging window expired." } } } } }, "description": "Customer care messaging window expired.\n\n> You can message WhatsApp users with session messages only while the customer\ncare messaging window is open. Outside this window, only `template` messages\nare allowed.\n>\n> Do not assume a fixed duration: the window depends on what opened the\nconversation (an ad click lasts considerably longer than an organic message)\nand Meta changes it over time. Read `messaging_window_expires_at` from the\nChat's contact instead." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageWabaErrorResponse" }, "examples": { "503": { "value": { "reason": "Message gateway is unavailable." } } } } }, "description": "The message gateway could not be reached.\n\n> Retry after a few seconds. Read the Chat's messages first if you need to be\ncertain: a request that timed out rather than being refused may have queued\nthe message before the gateway stopped answering." } } } }, "/api/v1/messages/{id}/": { "get": { "operationId": "retrieveMessage", "description": "Get a single Message by its Inbox message ID.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "A unique value identifying this message.", "required": true } ], "tags": [ "Messages" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveMessage" } } }, "description": "" } } } }, "/api/v1/persons/": { "get": { "operationId": "listPeople", "description": "Filter Persons by string query - search for Persons containing specified text phrase.\n\nThe API will search in following places:\n\n* `waba_payload.wa_id`\n\n* `waba_payload.profile.name`", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "in": "query", "name": "search", "schema": { "type": "string" } } ], "tags": [ "Persons" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPersonList" } } }, "description": "" } } } }, "/api/v1/persons/{wa_id}/": { "get": { "operationId": "retrievePerson", "parameters": [ { "in": "path", "name": "wa_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "Persons" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } }, "description": "" } } } }, "/api/v1/saved_responses/": { "get": { "operationId": "listSavedResponses", "description": "List saved responses: the reusable replies your team can insert in the hosted Inbox.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } }, { "in": "query", "name": "text", "schema": { "type": "string" }, "description": "Search text in saved responses" } ], "tags": [ "Saved Responses" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSavedResponseList" } } }, "description": "" } } }, "post": { "operationId": "createSavedResponse", "description": "Create a saved response.", "tags": [ "Saved Responses" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedResponse" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SavedResponse" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SavedResponse" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedResponse" } } }, "description": "" } } } }, "/api/v1/saved_responses/{id}/": { "delete": { "operationId": "deleteSavedResponse", "description": "Delete a saved response.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this saved response.", "required": true } ], "tags": [ "Saved Responses" ], "responses": { "204": { "description": "No response body" } } } }, "/api/v1/settings/business/profile/": { "get": { "operationId": "retrieveBusinessProfileSettings", "tags": [ "Business Profile" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProfileSettings" } } }, "description": "" } } }, "patch": { "operationId": "partialUpdateBusinessProfileSettings", "tags": [ "Business Profile" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedBusinessProfileSettings" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedBusinessProfileSettings" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedBusinessProfileSettings" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProfileSettings" } } }, "description": "" } } } }, "/api/v1/settings/profile/photo/": { "get": { "operationId": "retrieveProfilePhoto", "description": "Retrieve Profile Photo - only available for admin Users.", "tags": [ "Business Profile" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string", "format": "binary" } } }, "description": "" } } }, "post": { "operationId": "updateProfilePhoto", "description": "Update Profile Photo - only available for admin Users.", "tags": [ "Business Profile" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfilePhoto" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ProfilePhoto" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProfilePhoto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfilePhoto" } } }, "description": "" } } }, "delete": { "operationId": "deleteProfilePhoto", "description": "Delete Profile Photo - only available for admin Users.", "tags": [ "Business Profile" ], "responses": { "204": { "description": "No response body" } } } }, "/api/v1/settings/refresh/issue/": { "post": { "operationId": "issueSettingsRefreshRequest", "tags": [ "Business Profile" ], "responses": { "202": { "description": "Refresh operation is started and response is given immediately, before finish." } } } }, "/api/v1/settings/refresh/status/": { "get": { "operationId": "checkSettingsRefreshStatus", "tags": [ "Business Profile" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshStatus" } } }, "description": "" } } } }, "/api/v1/settings/useravailability/": { "get": { "operationId": "getUserAvailabilitySettings", "description": "Singleton resource served at /settings/useravailability/ (no pk).", "tags": [ "Chats" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAvailabilitySettings" } } }, "description": "" } } }, "put": { "operationId": "updateUserAvailabilitySettings", "description": "Singleton resource served at /settings/useravailability/ (no pk).", "tags": [ "Chats" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAvailabilitySettings" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/UserAvailabilitySettings" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UserAvailabilitySettings" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAvailabilitySettings" } } }, "description": "" } } }, "patch": { "operationId": "partialUpdateUserAvailabilitySettings", "description": "Singleton resource served at /settings/useravailability/ (no pk).", "tags": [ "Chats" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedUserAvailabilitySettings" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedUserAvailabilitySettings" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedUserAvailabilitySettings" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAvailabilitySettings" } } }, "description": "" } } } }, "/api/v1/status/health/": { "get": { "operationId": "listHealthStatuses", "description": "Check the health status(es) of your inbox", "tags": [ "Status" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HealthStatus" } } } }, "description": "" } } } }, "/api/v1/status/instance/": { "get": { "operationId": "getInstanceStatus", "description": "Get the status of this inbox instance.", "tags": [ "Status" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceStatus" } } } }, "description": "" } } } }, "/api/v1/tags/": { "get": { "operationId": "listTags", "description": "List all Tags that can be used on Chats and Messages.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "Tags" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTagList" } } }, "description": "" } } }, "post": { "operationId": "createTag", "description": "Create a new Tag that can be later used to tag Messages or Chats", "tags": [ "Tags" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Tag" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Tag" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } }, "description": "" } } } }, "/api/v1/tags/{id}/": { "delete": { "operationId": "destroyTag", "description": "Delete a Tag. It is removed from every Chat and Message that has it.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this tag.", "required": true } ], "tags": [ "Tags" ], "responses": { "204": { "description": "No response body" } } } }, "/api/v1/templates/": { "get": { "operationId": "listTemplates", "description": "List all your message templates.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "Templates" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTemplateList" } } }, "description": "" } } }, "post": { "operationId": "createTemplate", "description": "Create a new message template.\n\nEditing templates is not supported.\nTo update one of your templates, please delete current template\nand then create a new one.\n\nEntire body schema follows schema as explained in\n[WhatsApp Business API Message Templates documentation](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates).\n\nIn above link, you can find more information about parameters, components, and buttons.\nThere is also a list of all supported languages\n[here](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates#response).\n\nThe template is created via the\n[360dialog Messaging API](https://docs.360dialog.com/docs/messaging-api/api-reference/templates)\nand the result object contains `id`, `status` and `category` of the new template.", "tags": [ "Templates" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Template" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Template" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } }, "description": "" } } } }, "/api/v1/templates/{name}/": { "delete": { "operationId": "destroyTemplate", "description": "Delete a given message template.\n\nThe template is deleted by name, in all languages it exists in.", "parameters": [ { "in": "path", "name": "name", "schema": { "type": "string" }, "required": true } ], "tags": [ "Templates" ], "responses": { "204": { "description": "No response body" } } } }, "/api/v1/templates/refresh/issue/": { "post": { "operationId": "issueTemplateRefreshStatus", "tags": [ "Templates" ], "responses": { "202": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} }, "examples": { "202": { "value": {} } } } }, "description": "Refresh operation is started and response is given immediately, before finish." } } } }, "/api/v1/templates/refresh/status/": { "get": { "operationId": "checkTemplateRefreshStatus", "tags": [ "Templates" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshStatus" } } }, "description": "" } } } }, "/api/v1/users/": { "get": { "operationId": "listUsers", "description": "List the Users of your Inbox.", "parameters": [ { "in": "query", "name": "include_assigned_wa_ids", "schema": { "type": "string" }, "description": "If true, includes the \"assigned_wa_ids\" field in the response." }, { "in": "query", "name": "is_available", "schema": { "type": "boolean" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "Users" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedUserList" } } }, "description": "" } } }, "post": { "operationId": "createNewUser", "description": "Creates a new User. Only admin Users can create new Users.\n\n**IMPORTANT:** Heads up! This request response returns an `activation_url` field, which is returned this way only once!\n\nWhen you create a new User using this API, you need to call returned `activation_url` in order to activate\nnewly created account.\n\n### Activating app Users\n\nIf you created a new User with role `\"app\"`,\ncalling the `activation_url` will result with a JSON response\nequal to Token Authorization request response, for example:\n\n```\n{\"token\": \"8aeb44f5a318542d32bb13019d68198467ee21f0\"}\n```\n\nYou can then use this token with no need to set any password for this User.\n\nNote that for `\"app\"` users, the activation code is no longer valid after the token is returned!\n\n### Activating regular and admin Users\n\nWhen creating regular users, you might want to set password first and then activate the User afterwards.\nUse `/users/{id}/password/change/`\nto set a password for this new User and then activate it.\n\nIf you integrate our API to an external system, you can integrate this URL so that users activate\ntheir accounts themselves either via email or any other solution you're using.\n\nAfter activation URL is called, the account is ready to be used.", "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewUser" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/NewUser" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/NewUser" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewUser" } } }, "description": "" } } } }, "/api/v1/users/{id}/password/change/": { "put": { "operationId": "changeUserPassword", "description": "Change password of somebody else (only available for admins)", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Password" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Password" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Password" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Password" } } }, "description": "" } } } }, "/api/v1/users/{id}/": { "get": { "operationId": "retrieveUser", "description": "Get a single User.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this user.", "required": true } ], "tags": [ "Users" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "" } } }, "put": { "operationId": "updateUser", "description": "Update user data - all fields are required.\nOnly admin Users can update all fields of other Users. Regular Users can update only the following fields, and only of their own User object: `\"username\"`, `\"first_name\"`, `\"last_name\"`, `\"email\"`.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this user.", "required": true } ], "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/User" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/User" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "" } } }, "patch": { "operationId": "partialUpdateUser", "description": "Partially update user data - all fields are optional.\nOnly admin Users can update all fields of other Users. Regular Users can update only the following fields, and only of their own User object: `\"username\"`, `\"first_name\"`, `\"last_name\"`, `\"email\"`.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this user.", "required": true } ], "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedUser" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedUser" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedUser" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "" } } } }, "/api/v1/users/{id}/availability/": { "patch": { "operationId": "updateAvailability", "description": "Allows users to set their 'is_available' status.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this user.", "required": true } ], "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedAvailability" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedAvailability" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedAvailability" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } }, "description": "" } } } }, "/api/v1/users/current/": { "get": { "operationId": "retrieveCurrentUser", "description": "Get object of currently logged in User", "tags": [ "Users" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "" } } } }, "/api/v1/users/password/change/": { "put": { "operationId": "changeMyPassword", "description": "Change your password (currently logged in User)", "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyPassword" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/MyPassword" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MyPassword" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyPassword" } } }, "description": "" } } } }, "/api/v1/webhooks/waba/": { "get": { "operationId": "listWabaWebhooks", "description": "Webhook sent by WhatsApp Business API to your endpoint(s)\n\nOnly admin Users can see a list of all Users WABA Webhooks.\nOther Users receive a list of one element of their own WABA Webhook (if configured).\n\nThis resource describes configuration of webhook sent from WhatsApp Business API / WhatsApp to one of your apps\n(or systems). WhatsApp Business API itself allows you to integrate only one webhook. With our API you can set up\nmultiple per-user webhooks.\n\nSee Integration chapter to learn more about per-user webhooks.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "Webhooks" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedWabaWebhookList" } } }, "description": "" } } }, "post": { "operationId": "createWabaWebhook", "description": "One user can have multiple WABA Webhook configs, for example:\n\n```json\n[{\n \"id\": 1,\n \"user\": {\"id\": 23, \"username\": \"string\", \"url\": \"string\"},\n \"url\": \"http://example.com\",\n \"on_incoming_message\": true,\n \"on_outgoing_message\": false,\n \"on_assigned\": false\n}, {\n \"id\": 2,\n \"user\": {\"id\": 23, \"username\": \"string\", \"url\": \"string\"},\n \"url\": \"http://example.com\",\n \"on_incoming_message\": false,\n \"on_outgoing_message\": true,\n \"on_assigned\": false,\n \"headers\": {}\n}, {\n \"id\": 3,\n \"user\": {\"id\": 23, \"username\": \"string\", \"url\": \"string\"},\n \"url\": \"http://example.com\",\n \"on_incoming_message\": false,\n \"on_outgoing_message\": false,\n \"on_assigned\": true,\n \"headers\": {\"Authorization\": \"Token 8aeb44f5a318542d32bb13019d68198467ee21f0\"}\n}]\n```\n\nor you can have following webhooks:\n\n```json\n[{\n \"id\": 1,\n \"user\": {\"id\": 23, \"username\": \"string\", \"url\": \"string\"},\n \"url\": \"http://example.com\",\n \"on_incoming_message\": true,\n \"on_outgoing_message\": true,\n \"on_assigned\": false\n}, {\n \"id\": 2,\n \"user\": {\"id\": 23, \"username\": \"string\", \"url\": \"string\"},\n \"url\": \"http://example.com\",\n \"on_incoming_message\": false,\n \"on_outgoing_message\": false,\n \"on_assigned\": true,\n \"headers\": {\"Authorization\": \"Token 8aeb44f5a318542d32bb13019d68198467ee21f0\"}\n}]\n```\n\nAfter this webhook is created, WABA webhooks are propagated to your URL starting from next webhook.\n\nSee WABA Webhook section to learn more how propagation works.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WabaWebhook" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WabaWebhook" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/WabaWebhook" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WabaWebhook" } } }, "description": "" } } } }, "/api/v1/webhooks/waba/{id}/": { "get": { "operationId": "retrieveWabaWebhook", "description": "Create WABA Webhook for this user (currently logged in user)", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this WABA webhook.", "required": true } ], "tags": [ "Webhooks" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WabaWebhook" } } }, "description": "" } } }, "put": { "operationId": "updateWabaWebhook", "description": "Update a WhatsApp webhook: its URL, the events it is called for, and its headers.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this WABA webhook.", "required": true } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WabaWebhook" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WabaWebhook" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/WabaWebhook" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WabaWebhook" } } }, "description": "" } } }, "delete": { "operationId": "deleteWabaWebhook", "description": "Deletes WABA Webhook permanently", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this WABA webhook.", "required": true } ], "tags": [ "Webhooks" ], "responses": { "204": { "description": "No response body" } } } }, "/api/v1/webhooks/waba/{id}/test/": { "get": { "operationId": "testWabaWebhook", "description": "Test the WABA Webhook, by sending a mock \"statuses\" HTTP POST request to its target url", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this WABA webhook.", "required": true } ], "tags": [ "Webhooks" ], "responses": { "200": { "description": "No response body" } } } }, "/api/v1/whatsapp_accounts/": { "get": { "operationId": "listWhatsAppAccounts", "description": "List the WhatsApp accounts connected to this Inbox.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } }, { "in": "query", "name": "this_instance", "schema": { "type": "boolean" } } ], "tags": [ "WhatsApp Accounts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedWhatsAppAccountList" } } }, "description": "" } } } } }, "components": { "schemas": { "ActionEnum": { "enum": [ "added", "removed" ], "type": "string", "description": "* `added` - Added\n* `removed` - Removed" }, "AuthToken": { "type": "object", "properties": { "username": { "type": "string", "writeOnly": true }, "password": { "type": "string", "writeOnly": true }, "token": { "type": "string", "readOnly": true } }, "required": [ "password", "token", "username" ] }, "Availability": { "type": "object", "properties": { "is_available": { "type": "boolean", "description": "Manual status set by the user to indicate availability for communication." } } }, "BusinessProfileSettings": { "type": "object", "properties": { "address": { "type": "string" }, "description": { "type": "string" }, "email": { "type": "string", "format": "email" }, "messaging_product": { "allOf": [ { "$ref": "#/components/schemas/MessagingProductEnum" } ], "default": "whatsapp" }, "vertical": { "$ref": "#/components/schemas/VerticalEnum" }, "websites": { "type": "array", "items": {} } }, "required": [ "address", "description", "email", "vertical" ] }, "CanReadChatsEnum": { "enum": [ "all", "group", "user", "none" ], "type": "string", "description": "* `all` - All Chats\n* `group` - Only Chats assigned to User's Groups\n* `user` - Only Chats assigned to User directly\n* `none` - No Chats" }, "CanWriteToChatsEnum": { "enum": [ "all", "group", "user", "none" ], "type": "string", "description": "* `all` - All Chats\n* `group` - Only Chats assigned to User's Groups\n* `user` - Only Chats assigned to User directly\n* `none` - No Chats" }, "CaptionedMedia": { "type": "object", "description": "A media object that has `caption` field\n\nUsed in `document`, `image` and `video` media. Do **not** use with `audio` or `sticker` media.\n\nSee: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api#post-version-phone-number-id-messages", "properties": { "link": { "type": "string", "description": "This needs to be HTTPS URL to one of media uploaded to our API. See creating a new media file" }, "mime_type": { "type": "string", "description": "Mimetype of the media file. This parameter is optional, but providing it is recommended. It will be required for applications like inbox frontend, to be able to determine file type before it is actually downloaded from the `link`." }, "caption": { "type": "string", "description": "Caption of the media file" } }, "required": [ "link" ] }, "Chat": { "type": "object", "properties": { "contact": { "allOf": [ { "$ref": "#/components/schemas/Person" } ], "description": "Who are we talking to" }, "new_messages": { "type": "integer", "description": "The number of messages not received by currently authenticated user" }, "wa_id": { "type": "string", "description": "**Deprecated**" }, "bsuid": { "type": "string", "readOnly": true, "nullable": true, "title": "Business-Scoped User ID", "description": "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_number": { "type": "string", "readOnly": true, "nullable": true, "description": "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 \u2014 e.g. recent interaction within the last 30 days, or via Contact Book." }, "last_message": { "$ref": "#/components/schemas/RetrieveMessage" }, "assigned_to_user": { "$ref": "#/components/schemas/User" }, "assigned_group": { "$ref": "#/components/schemas/Group" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tagging" } }, "thread_controller": { "readOnly": true, "nullable": true, "description": "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.\n\n* `mba` - Meta Business Agent\n* `inbox` - Inbox", "oneOf": [ { "$ref": "#/components/schemas/ThreadControllerEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] } }, "required": [ "assigned_group", "assigned_to_user", "bsuid", "contact", "last_message", "new_messages", "phone_number", "tags", "thread_controller", "wa_id" ] }, "ChatAssignment": { "type": "object", "properties": { "wa_id": { "type": "string", "title": "WhatsApp id", "description": "WhatsApp ID \u2014 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.", "pattern": "^([A-Z]{2}\\.(ENT\\.)?[a-zA-Z0-9]+|[0-9]+)$", "maxLength": 200 }, "bsuid": { "type": "string", "readOnly": true, "nullable": true, "title": "Business-Scoped User ID", "description": "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_number": { "type": "string", "readOnly": true, "nullable": true, "description": "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 \u2014 e.g. recent interaction within the last 30 days, or via Contact Book." }, "assigned_to_user": { "type": "integer", "nullable": true }, "assigned_group": { "type": "integer", "nullable": true } }, "required": [ "bsuid", "phone_number", "wa_id" ] }, "ChatAssignmentEvent": { "type": "object", "properties": { "timestamp": { "type": "number", "format": "double" }, "wa_id": { "type": "string", "title": "WhatsApp id", "description": "WhatsApp ID of the Chat for which the assignment was changed", "maxLength": 1000 }, "assigned_to_user_set": { "$ref": "#/components/schemas/User" }, "assigned_to_user_was_cleared": { "type": "boolean" }, "assigned_group_set": { "$ref": "#/components/schemas/Group" }, "assigned_group_was_cleared": { "type": "boolean", "title": "Assigned to group was cleared" }, "done_by": { "$ref": "#/components/schemas/User" } }, "required": [ "assigned_group_set", "assigned_to_user_set", "done_by", "timestamp" ] }, "ChatAutoAssignment": { "type": "object", "properties": { "wa_id": { "type": "string", "readOnly": true, "title": "WhatsApp id", "description": "WhatsApp ID \u2014 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." }, "assigned_to_user": { "type": "integer", "readOnly": true, "nullable": true, "description": "ID of the User this Chat is assigned to" } }, "required": [ "assigned_to_user", "wa_id" ] }, "ChatImportContact": { "type": "object", "properties": { "handle": { "type": "string", "description": "Name of message sender as seen in device's contacts and the WhatsApp chat export (text part)" }, "phone_number": { "type": "string", "description": "Phone number of contact" } }, "required": [ "handle", "phone_number" ] }, "ChatImportMediaFile": { "type": "object", "properties": { "b64_content": { "type": "string", "description": "Content of media file, encoded with base64" }, "mime_type": { "type": "string", "description": "MIME type of media file" }, "file_name": { "type": "string", "description": "File name of media file as given to you by WhatsApp" } }, "required": [ "b64_content", "file_name", "mime_type" ] }, "ChatImportRequest": { "type": "object", "properties": { "chat_text": { "type": "string", "description": "The text chat log as given to you by WhatsApp" }, "chat_participants": { "type": "array", "items": { "$ref": "#/components/schemas/ChatImportContact" }, "description": "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": { "type": "integer", "description": "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": { "type": "string", "description": "Locale code of device's system language, and optionally, country" }, "media_files": { "type": "array", "items": { "$ref": "#/components/schemas/ChatImportMediaFile" } } }, "required": [ "chat_text", "device_language_code", "media_files", "utc_offset_minutes" ] }, "ChatTagging": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "tag": { "type": "integer", "description": "ID of related Tag" }, "chat": { "type": "string", "title": "WhatsApp id", "description": "WhatsApp ID \u2014 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." }, "extra": { "nullable": true, "description": "Optional additional data. Should not be used on front-end apps. Use only to pass extra data between systems / apps / bots, when Chat is tagged." } }, "required": [ "chat", "id", "tag" ] }, "ChatTaggingEvent": { "type": "object", "properties": { "timestamp": { "type": "number", "format": "double" }, "action": { "$ref": "#/components/schemas/ActionEnum" }, "tag": { "$ref": "#/components/schemas/Tag" }, "chat": { "type": "string", "title": "WhatsApp id", "description": "WhatsApp ID \u2014 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.", "readOnly": true }, "extra": { "nullable": true, "description": "Optional additional data. Should not be used on front-end apps. Use only to pass extra data between systems / apps / bots, when Chat is tagged." }, "done_by": { "$ref": "#/components/schemas/User" } }, "required": [ "action", "chat", "done_by", "tag", "timestamp" ] }, "Contact": { "type": "object", "properties": { "person": { "allOf": [ { "$ref": "#/components/schemas/Person" } ], "description": "Person related to this contact. Can be `null` if this person wasn't yet contacted via your inbox or related Person data was removed from your inbox." }, "contact_provider_results": { "type": "array", "items": { "$ref": "#/components/schemas/ContactProviderResult" }, "description": "Deprecated, always empty" } }, "required": [ "contact_provider_results" ] }, "ContactBlock": { "type": "object", "properties": { "reason": { "type": "string", "default": "", "description": "Optional string with max length 60. Free form block reason. Will be used when another business account is being blocked. ", "maxLength": 60 } } }, "ContactModel": { "type": "object", "description": "Serializes the Contact model similar to how Contact Providers serialized contacts in the past.", "properties": { "name": { "type": "string", "readOnly": true, "description": "Name of the person" }, "initials": { "type": "string", "description": "Contact name initials used for display when avatar image is missing" }, "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/ContactModelPhoneNumber" }, "description": "At least one phone number (that should be equal to `wa_id`). " }, "email_addresses": { "type": "array", "items": {}, "description": "Deprecated, always empty" }, "urls": { "type": "array", "items": {}, "description": "Deprecated, always empty" }, "contact_provider": { "description": "Deprecated, always a dummy value" } }, "required": [ "contact_provider", "email_addresses", "initials", "name", "phone_numbers", "urls" ] }, "ContactModelPhoneNumber": { "type": "object", "properties": { "phone_number": { "type": "string", "description": "Person's phone number. Should be equal to `wa_id`." } }, "required": [ "phone_number" ] }, "ContactProvider": { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/ContactProviderTypeEnum" } ], "description": "Contact Provider type, if known.\n\nAllows you to identify contact provider type programmatically, so that you are able to display it accordingly or provide a valid linking to external app or system.\n\nIf data was returned by a Contact Provider type known to us (for example a Inbox-supported plugin), then this field will allow you to identify the exact source of contact data. In other case (for example external plugin), `\"other\"` is returned.\n\n* `google` - google\n* `hubspot` - hubspot\n* `other` - other" }, "name": { "type": "string", "description": "Contact Provider human-readable name, if known.\n\nAllows you to identify contact source visually. Should be displayed on the frontend." }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier of this Contact Provider.\n\nAllows you to distinguish different integrations of the same Contact Provider type." } }, "required": [ "id", "type" ] }, "ContactProviderPhoneNumber": { "type": "object", "properties": { "phone_number": { "type": "string", "description": "Person's phone number. Should be equal to `wa_id`." }, "description": { "type": "string", "description": "Phone number description, like \"Work\", \"Home\" or \"Office\", if provided. (Can be any string value)" } }, "required": [ "phone_number" ] }, "ContactProviderResult": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the person as returned by related Contact Provider" }, "initials": { "type": "string", "description": "Contact name initials used for display when avatar image is missing" }, "avatar": { "type": "string", "format": "uri", "description": "URL leading to contact miniature avatar or miniature photo, if available" }, "large_avatar": { "type": "string", "format": "uri", "description": "URL leading to contact large avatar or large photo, if available" }, "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/ContactProviderPhoneNumber" }, "description": "At least one phone number (that should be equal to `wa_id`). " }, "email_addresses": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" }, "description": "E-mail addresses of this Person, if provided." }, "urls": { "type": "array", "items": { "$ref": "#/components/schemas/Url" }, "description": "URLs of this Person, if provided." }, "contact_provider": { "allOf": [ { "$ref": "#/components/schemas/ContactProvider" } ], "description": "Contact Provider that provided this object" } }, "required": [ "contact_provider", "email_addresses", "initials", "name", "phone_numbers", "urls" ] }, "ContactProviderTypeEnum": { "enum": [ "google", "hubspot", "other" ], "type": "string", "description": "* `google` - google\n* `hubspot` - hubspot\n* `other` - other" }, "ContactReport": { "type": "object", "properties": { "reason": { "type": "string", "default": "", "description": "Optional string with max length 60. Free form block reason. Will be used when another business account is being blocked. ", "maxLength": 60 }, "block": { "type": "boolean", "default": false, "description": "True or false optional boolean with default of false" }, "message_id": { "type": "string", "description": "Optional reported message id" } } }, "ContactsBlockListResponse": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactsBlockListWabaContactsResponse" } }, "pagination": { "$ref": "#/components/schemas/ContactsBlockListWabaPaginationResponse" } }, "required": [ "contacts", "pagination" ] }, "ContactsBlockListWabaContactsResponse": { "type": "object", "properties": { "wa_id": { "type": "string" } }, "required": [ "wa_id" ] }, "ContactsBlockListWabaPaginationResponse": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "limit", "offset", "total" ] }, "ContactsBlockOrReport400ErrorResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "title": { "type": "string" }, "details": { "type": "string" } }, "required": [ "code", "details", "title" ] }, "ContactsBlockOrReport400Response": { "type": "object", "properties": { "meta": {}, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ContactsBlockOrReport400ErrorResponse" } } }, "required": [ "errors", "meta" ] }, "CreateMedia": { "type": "object", "properties": { "file_encoded": { "type": "string", "format": "uri", "writeOnly": true }, "file": { "type": "string", "format": "uri", "readOnly": true, "description": "An authorization-free link to your media file. This link will contain query params: `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)" }, "id": { "type": "string", "format": "uuid", "readOnly": true } }, "required": [ "file", "file_encoded", "id" ] }, "CreateMessage": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CreateMessageTypeEnum" }, "verify_contact": { "type": "boolean", "nullable": true, "default": false, "description": "\n**Deprecated parameter**: Will be treated as false regardless of value, as contact verification has been removed from\nWhatsApp side.\n\nSee endpoint description. It has been updated to reflect the new workflow.\n" }, "text": { "$ref": "#/components/schemas/MessageText" }, "image": { "$ref": "#/components/schemas/CaptionedMedia" }, "contacts": { "description": "See [Contact Messages WhatsApp Business API Documentation](https://developers.facebook.com/docs/whatsapp/api/messages/others#contacts-messages)" }, "document": { "$ref": "#/components/schemas/MessageDocument" }, "hsm": { "description": "**Deprecated:** The `hsm` object has been deprecated with v2.39 of the WhatsApp Business API.See [2.39.1 changelog](https://developers.facebook.com/docs/whatsapp/on-premises/changelog#wa239) and [WhatsApp Business API Documentation](https://developers.facebook.com/docs/whatsapp/on-premises/reference/messages#hsm-object)." }, "location": { "description": "See [Location Messages WhatsApp Business API Documentation](https://developers.facebook.com/docs/whatsapp/api/messages/others#locations)" }, "sticker": { "$ref": "#/components/schemas/MessageSticker" }, "template": { "description": "See [Template Messages WhatsApp Business API Documentation](https://developers.facebook.com/docs/whatsapp/message-templates/creation)" }, "audio": { "$ref": "#/components/schemas/MessageMedia" }, "video": { "$ref": "#/components/schemas/CaptionedMedia" }, "interactive": { "description": "See [`interactive` object in WhatsApp Business API Documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api#post-version-phone-number-id-messages)" }, "reaction": { "$ref": "#/components/schemas/MessageReaction" }, "wa_id": { "type": "string", "description": "WhatsApp ID of the message recipient \u2014 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]+)$" } }, "required": [ "type", "wa_id" ] }, "CreateMessageTypeEnum": { "enum": [ "text", "image", "contacts", "document", "hsm", "location", "sticker", "template", "audio", "video", "interactive", "reaction" ], "type": "string", "description": "* `text` - text\n* `image` - image\n* `contacts` - contacts\n* `document` - document\n* `hsm` - hsm\n* `location` - location\n* `sticker` - sticker\n* `template` - template\n* `audio` - audio\n* `video` - video\n* `interactive` - interactive\n* `reaction` - reaction" }, "EmailAddress": { "type": "object", "properties": { "email_address": { "type": "string", "format": "email" }, "description": { "type": "string", "description": "E-mail address description, like \"Work\", \"Home\" or \"Office\", if provided. (Can be any string value)" } }, "required": [ "email_address" ] }, "Group": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "maxLength": 1000 } }, "required": [ "id", "name" ] }, "GroupMember": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "HealthStatus": { "type": "object", "properties": { "check_name": { "type": "string", "readOnly": true }, "is_ok": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "check_name", "is_ok", "message" ] }, "InstanceStatus": { "type": "object", "properties": { "waba_stack_configured": { "type": "boolean" }, "waba_stack_connection_stable": { "type": "boolean" }, "last_interaction": { "type": "number", "format": "double", "nullable": true } }, "required": [ "last_interaction", "waba_stack_configured", "waba_stack_connection_stable" ] }, "MarkAsReceivedMessage452Response": { "type": "object", "properties": { "reason": { "type": "string" }, "timestamp": { "type": "number", "format": "double" }, "server_timestamp": { "type": "number", "format": "double" } }, "required": [ "reason", "server_timestamp", "timestamp" ] }, "MarkAsReceivedMessage453Response": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] }, "MediaCreateRequest": { "type": "object", "properties": { "file_encoded": { "type": "string", "description": "Encoded in [Base64](https://en.wikipedia.org/wiki/Base64)." } }, "required": [ "file_encoded" ] }, "MessageDocument": { "type": "object", "description": "A media object that has `caption` field\n\nUsed in `document`, `image` and `video` media. Do **not** use with `audio` or `sticker` media.\n\nSee: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api#post-version-phone-number-id-messages", "properties": { "link": { "type": "string", "description": "This needs to be HTTPS URL to one of media uploaded to our API. See creating a new media file" }, "mime_type": { "type": "string", "description": "Mimetype of the media file. This parameter is optional, but providing it is recommended. It will be required for applications like inbox frontend, to be able to determine file type before it is actually downloaded from the `link`." }, "caption": { "type": "string", "description": "Caption of the media file. WhatsApp does not display caption to end users when sending a document type of message, but WhatsApp uses the caption field as a fallback when filename field is missing." }, "filename": { "type": "string", "description": "Describes the filename for the specific document. If not provided, caption field will be used as a fallback." } }, "required": [ "link" ] }, "MessageMedia": { "type": "object", "description": "Media file common fields\n\n`link` is used in `audio`, `document`, `image`, `sticker` and `video` type of messages.\n\nWe're not using Business API's `id` field, so this makes `link` field always required.\n\nSee: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api#post-version-phone-number-id-messages\n\nOptionally we take `mime_type` in addition to what's on Business API side, because incoming messages provide\n`mime_type` in `waba_payload`. This gives consistent payload for applications like inbox frontend, where\nmedia file type can be determined before it is actually downloaded.", "properties": { "link": { "type": "string", "description": "This needs to be HTTPS URL to one of media uploaded to our API. See creating a new media file" }, "mime_type": { "type": "string", "description": "Mimetype of the media file. This parameter is optional, but providing it is recommended. It will be required for applications like inbox frontend, to be able to determine file type before it is actually downloaded from the `link`." } }, "required": [ "link" ] }, "MessageReaction": { "type": "object", "properties": { "message_id": { "type": "string", "description": "\nWhatsApp message ID of message you want to apply the emoji to.\n\nIf the message you are reacting to is more than 30 days old, doesn't correspond to any message in the conversation, has been deleted, or is itself a reaction message, the reaction message will not be delivered and you will receive a messages webhook with error code 131009.\n", "maxLength": 300 }, "emoji": { "type": "string", "description": "\nUnicode escape sequence of the emoji, or the emoji itself, to apply to the user message.\nFor example: `\"\\uD83D\\uDE00\"` or `\"\ud83d\ude00\"`\n", "maxLength": 100 } }, "required": [ "emoji", "message_id" ] }, "MessageSendSuccessfulResponse": { "type": "object", "properties": { "reason": { "type": "string" }, "id": { "type": "string", "description": "Internal Inbox message ID that was generated when adding Message to queue.\n You will receive this value as `\"getchat_id\"` in `\"statuses\"` events sent to your webhook(s)." } }, "required": [ "id" ] }, "MessageSticker": { "type": "object", "properties": { "link": { "type": "string", "description": "HTTPS link to a sticker file" } }, "required": [ "link" ] }, "MessageTagging": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true, "description": "This tagging relation ID. Used when deleting a tagging for example." }, "tag": { "type": "integer", "description": "ID of related Tag" }, "message": { "type": "string", "description": "Message ID string known from WABA payload" }, "extra": { "nullable": true, "description": "Optional additional data. Should not be used on front-end apps. Use only to pass extra data between systems / apps / bots, when Message is tagged." } }, "required": [ "id", "message", "tag" ] }, "MessageTaggingEvent": { "type": "object", "properties": { "timestamp": { "type": "number", "format": "double" }, "action": { "$ref": "#/components/schemas/ActionEnum" }, "tag": { "$ref": "#/components/schemas/Tag" }, "message": { "type": "string", "description": "Message ID string known from WABA payload" }, "extra": { "nullable": true, "description": "Optional additional data. Should not be used on front-end apps. Use only to pass extra data between systems / apps / bots, when Message is tagged." }, "done_by": { "$ref": "#/components/schemas/User" } }, "required": [ "action", "done_by", "message", "tag", "timestamp" ] }, "MessageText": { "type": "object", "properties": { "body": { "type": "string" }, "preview_url": { "type": "boolean", "description": "Set to true to have the WhatsApp client attempt to render a link preview for the first URL in the body text. URLs must begin with http:// or https://. See: https://developers.facebook.com/docs/whatsapp/cloud-api/messages/text-messages" } }, "required": [ "body" ] }, "MessageWabaErrorInvalidWaIdResponse": { "type": "object", "properties": { "reason": { "type": "string" }, "waba_response": {} }, "required": [ "reason", "waba_response" ] }, "MessageWabaErrorResponse": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] }, "MessagingProductEnum": { "enum": [ "whatsapp" ], "type": "string", "description": "* `whatsapp` - whatsapp" }, "MyPassword": { "type": "object", "properties": { "current_password": { "type": "string", "writeOnly": true, "description": "Provide current password for security" }, "new_password": { "type": "string", "writeOnly": true, "description": "Provide a new password that will be set to your account now" } }, "required": [ "current_password", "new_password" ] }, "NewUser": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "readOnly": true }, "activation_url": { "type": "string", "format": "uri", "readOnly": true, "description": "Success! Your account is now created! Use this link to activate your account and set your password. You can open this link in any way while using this API. See this endpoint description to learn more on how activation URL works." }, "activation_email_sent": { "type": "boolean", "readOnly": true, "description": "Whether an invitation carrying the `activation_url` was e-mailed to the address in the `email` field.\n\nIt is `false` when no address was given, when the User has the \"app\" role (their activation link answers with an API token, which is not sent by e-mail), when activation e-mails are switched off for this inbox, or when the delivery failed. The account is created either way, so hand the `activation_url` over yourself when this is `false`." }, "id": { "type": "integer", "readOnly": true }, "username": { "type": "string", "description": "Username that is used in combination with password during login.\n\nOnly alphanumeric characters are allowed (A-Z, a-z, 0-9)." }, "first_name": { "type": "string", "maxLength": 150 }, "last_name": { "type": "string", "maxLength": 150 }, "email": { "type": "string", "format": "email" }, "profile": { "allOf": [ { "$ref": "#/components/schemas/UserProfile" } ], "description": "Optional field used to create app users and additional admin users" } }, "required": [ "activation_email_sent", "activation_url", "id", "url", "username" ] }, "NullEnum": { "enum": [ null ] }, "PaginatedChatAssignmentEventList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ChatAssignmentEvent" } } } }, "PaginatedChatList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Chat" } } } }, "PaginatedChatTaggingEventList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ChatTaggingEvent" } } } }, "PaginatedContactModelList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ContactModel" } } } }, "PaginatedGroupList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } }, "PaginatedMessageTaggingEventList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/MessageTaggingEvent" } } } }, "PaginatedPersonList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } } } }, "PaginatedRetrieveMessageList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieveMessage" } } } }, "PaginatedSavedResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SavedResponse" } } } }, "PaginatedTagList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } }, "PaginatedTemplateList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } }, "PaginatedUserList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } }, "PaginatedWabaErrorList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WabaError" } } } }, "PaginatedWabaWebhookList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WabaWebhook" } } } }, "PaginatedWhatsAppAccountList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsAppAccount" } } } }, "Password": { "type": "object", "properties": { "password": { "type": "string", "writeOnly": true } }, "required": [ "password" ] }, "PatchedAvailability": { "type": "object", "properties": { "is_available": { "type": "boolean", "description": "Manual status set by the user to indicate availability for communication." } } }, "PatchedBusinessProfileSettings": { "type": "object", "properties": { "address": { "type": "string" }, "description": { "type": "string" }, "email": { "type": "string", "format": "email" }, "messaging_product": { "allOf": [ { "$ref": "#/components/schemas/MessagingProductEnum" } ], "default": "whatsapp" }, "vertical": { "$ref": "#/components/schemas/VerticalEnum" }, "websites": { "type": "array", "items": {} } } }, "PatchedChatAssignment": { "type": "object", "properties": { "wa_id": { "type": "string", "title": "WhatsApp id", "description": "WhatsApp ID \u2014 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.", "pattern": "^([A-Z]{2}\\.(ENT\\.)?[a-zA-Z0-9]+|[0-9]+)$", "maxLength": 200 }, "bsuid": { "type": "string", "readOnly": true, "nullable": true, "title": "Business-Scoped User ID", "description": "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_number": { "type": "string", "readOnly": true, "nullable": true, "description": "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 \u2014 e.g. recent interaction within the last 30 days, or via Contact Book." }, "assigned_to_user": { "type": "integer", "nullable": true }, "assigned_group": { "type": "integer", "nullable": true } } }, "PatchedResolvedChat": { "type": "object", "properties": { "wa_id": { "type": "string", "readOnly": true, "title": "WhatsApp id", "description": "WhatsApp ID \u2014 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." }, "bsuid": { "type": "string", "readOnly": true, "nullable": true, "title": "Business-Scoped User ID", "description": "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_number": { "type": "string", "readOnly": true, "nullable": true, "description": "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 \u2014 e.g. recent interaction within the last 30 days, or via Contact Book." }, "resolved": { "type": "boolean", "description": "Whether this chat is considered resolved by the assigned agent. Can automatically be set to false if contact keeps sending messages." } } }, "PatchedUser": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "readOnly": true }, "id": { "type": "integer", "readOnly": true }, "username": { "type": "string", "description": "Username that is used in combination with password during login.\n\nOnly alphanumeric characters are allowed (A-Z, a-z, 0-9)." }, "first_name": { "type": "string", "maxLength": 150 }, "last_name": { "type": "string", "maxLength": 150 }, "email": { "type": "string", "format": "email", "description": "E-mail address of this new user.\n\n" }, "profile": { "allOf": [ { "$ref": "#/components/schemas/UserProfile" } ], "description": "Optional field used to create app users and additional admin users" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/GroupMember" }, "readOnly": true, "description": "List of group objects the user belongs to (read-only)" }, "group_ids": { "type": "array", "items": { "type": "integer", "writeOnly": true }, "writeOnly": true, "description": "List of group IDs to assign to the user (write-only)" }, "permissions": { "$ref": "#/components/schemas/Permissions" }, "assigned_wa_ids": { "type": "array", "items": { "type": "string" }, "readOnly": true } } }, "PatchedUserAvailabilitySettings": { "type": "object", "properties": { "feature_set_enabled": { "type": "boolean", "description": "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)" } } }, "Permissions": { "type": "object", "properties": { "can_use_tags": { "type": "boolean", "description": "Uncheck this to disable tagging for related Users completely." }, "can_read_chats": { "allOf": [ { "$ref": "#/components/schemas/CanReadChatsEnum" } ], "description": "

Possible values:
all - User can read from All Chats
\ngroup - User can read from Only Chats assigned to User's Groups
\nuser - User can read from Only Chats assigned to User directly
\nnone - User can read from No Chats

\n\n* `all` - All Chats\n* `group` - Only Chats assigned to User's Groups\n* `user` - Only Chats assigned to User directly\n* `none` - No Chats" }, "can_write_to_chats": { "allOf": [ { "$ref": "#/components/schemas/CanWriteToChatsEnum" } ], "description": "

Possible values:
all - User can write to All Chats
\ngroup - User can write to Only Chats assigned to User's Groups
\nuser - User can write to Only Chats assigned to User directly
\nnone - User can write to No Chats

\n\n* `all` - All Chats\n* `group` - Only Chats assigned to User's Groups\n* `user` - Only Chats assigned to User directly\n* `none` - No Chats" } } }, "Person": { "type": "object", "properties": { "wa_id": { "type": "string", "title": "WhatsApp id", "description": "WhatsApp ID \u2014 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.", "pattern": "^([A-Z]{2}\\.(ENT\\.)?[a-zA-Z0-9]+|[0-9]+)$", "maxLength": 200 }, "bsuid": { "type": "string", "readOnly": true, "nullable": true, "title": "Business-Scoped User ID", "description": "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_number": { "type": "string", "readOnly": true, "nullable": true, "description": "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 \u2014 e.g. recent interaction within the last 30 days, or via Contact Book." }, "waba_payload": { "$ref": "#/components/schemas/WabaPayloadContact" }, "initials": { "type": "string", "description": "Contact user name initials used for display when avatar image is missing" }, "last_message_timestamp": { "type": "number", "format": "double", "nullable": true, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time) of last message that was sent by this contact. It is the floor of the customer care messaging window: a non-template message can always be delivered for some time after the customer last wrote to your business, and Meta may keep the window open for longer \u2014 see `messaging_window_expires_at`. Read more at WhatsApp Business API docs [Messages Cut-off Control](https://developers.facebook.com/docs/whatsapp/api/messages#cut-off-control)." }, "messaging_window_expires_at": { "type": "number", "format": "double", "readOnly": true, "description": "[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time) after which a non-template message to this contact is rejected with HTTP 453. Derived from what Meta reported for this conversation, the customer's last message, and \u2014 for click-to-WhatsApp chats we have not replied to yet \u2014 the ad referral. Never assume a fixed duration: read this value." }, "messaging_window_origin": { "type": "string", "readOnly": true, "nullable": true, "description": "`conversation.origin.type` reported by Meta alongside `messaging_window_expires_at` \u2014 what opened the conversation (e.g. `service`, `marketing`, `utility`, `authentication`, or `referral_conversion` for a click-to-WhatsApp ad)." }, "resolved": { "type": "boolean", "description": "Whether this chat is considered resolved by the assigned agent. Can automatically be set to false if contact keeps sending messages." } }, "required": [ "bsuid", "initials", "messaging_window_expires_at", "messaging_window_origin", "phone_number", "wa_id", "waba_payload" ] }, "ProfilePhoto": { "type": "object", "properties": { "file_encoded": { "type": "string", "format": "uri", "writeOnly": true, "description": "Binary file" } }, "required": [ "file_encoded" ] }, "ReceivedMessageMark": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "A timestamp of the latest message that was received by the User calling this API.\n\nThis 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_id": { "type": "string", "description": "WhatsApp ID of the message sender" } }, "required": [ "customer_wa_id", "timestamp" ] }, "RefreshStatus": { "type": "object", "properties": { "currently_refreshing": { "type": "boolean", "default": false } } }, "ResolvedChat": { "type": "object", "properties": { "wa_id": { "type": "string", "readOnly": true, "title": "WhatsApp id", "description": "WhatsApp ID \u2014 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." }, "bsuid": { "type": "string", "readOnly": true, "nullable": true, "title": "Business-Scoped User ID", "description": "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_number": { "type": "string", "readOnly": true, "nullable": true, "description": "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 \u2014 e.g. recent interaction within the last 30 days, or via Contact Book." }, "resolved": { "type": "boolean", "description": "Whether this chat is considered resolved by the assigned agent. Can automatically be set to false if contact keeps sending messages." } }, "required": [ "bsuid", "phone_number", "wa_id" ] }, "RetrieveMessage": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal Inbox Message ID" }, "waba_payload": { "description": "See [Inbound Notifications from WhatsApp Business API](https://developers.facebook.com/docs/whatsapp/api/webhooks/inbound)" }, "waba_statuses": { "allOf": [ { "$ref": "#/components/schemas/WabaMessageStatuses" } ], "description": "Timestamps of all statuses of the message" }, "contact": { "allOf": [ { "$ref": "#/components/schemas/Person" } ], "description": "Who are we talking to" }, "from_us": { "type": "boolean", "readOnly": true, "title": "From us?", "description": "Allows to easily implement different display for messages sent by us or by customer." }, "received": { "type": "boolean", "default": false, "description": "Tells if this message was marked as received by you (currently logged in user)" }, "sender": { "allOf": [ { "$ref": "#/components/schemas/User" } ], "description": "Who is talking on our behalf\n\n`null` if this is an incoming message." }, "before_time": { "type": "integer" }, "since_time": { "type": "integer" }, "customer_wa_id": { "type": "string", "readOnly": true, "title": "Customer WhatsApp id", "description": "**Deprecated**" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tagging" }, "default": [], "description": "Tags assigned to this Message" }, "chat_tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tagging" }, "default": [], "description": "Tags assigned to the Chat this Message belongs to" }, "sent_by_mba": { "type": "boolean", "readOnly": true, "title": "Sent by Meta Business Agent", "description": "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." } }, "required": [ "contact", "customer_wa_id", "from_us", "id", "sent_by_mba", "waba_payload", "waba_statuses" ] }, "RoleEnum": { "enum": [ "user", "admin", "app" ], "type": "string", "description": "* `user` - Regular user\n* `admin` - Admin\n* `app` - App integration" }, "SavedResponse": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true, "description": "Primary ID." }, "text": { "type": "string" }, "created_by": { "type": "integer", "readOnly": true, "nullable": true }, "timestamp": { "type": "number", "format": "double", "readOnly": true } }, "required": [ "created_by", "id", "text", "timestamp" ] }, "ShortUser": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "username": { "type": "string", "description": "Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.", "pattern": "^[\\w.@+-]+$", "maxLength": 150 }, "url": { "type": "string", "format": "uri", "readOnly": true } }, "required": [ "id", "url", "username" ] }, "Tag": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "maxLength": 1000 }, "web_inbox_color": { "type": "string", "nullable": true, "description": "A Web App related setting - which color to show on the Web App frontend", "maxLength": 1000 } }, "required": [ "id", "name" ] }, "Tagging": { "type": "object", "properties": { "name": { "type": "string", "description": "Tag object name" }, "web_inbox_color": { "type": "string", "description": "A Web App related setting - which color to show on the Web App frontend" }, "tagging_id": { "type": "integer", "readOnly": true, "description": "This tagging relation ID. Used when deleting a Tagging for example." }, "id": { "type": "integer", "description": "Tag object unique ID" }, "extra": { "description": "Tagging extra payload" } }, "required": [ "id", "name", "tagging_id", "web_inbox_color" ] }, "Template": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the message template." }, "category": { "type": "string", "description": "The type of message template.\n Values: ACCOUNT_UPDATE, PAYMENT_UPDATE, PERSONAL_FINANCE_UPDATE, SHIPPING_UPDATE, RESERVATION_UPDATE,\n ISSUE_RESOLUTION, APPOINTMENT_UPDATE, TRANSPORTATION_UPDATE, TICKET_UPDATE, ALERT_UPDATE, AUTO_REPLY\n " }, "language": { "type": "string", "description": "The language of message template, e.g. `en_US`" }, "components": { "type": "array", "items": {}, "description": "The list of definitions of parts of\n message template. See\n [WhatsApp Business API Documentation](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates).\n " }, "id": { "type": "string", "readOnly": true }, "rejected_reason": { "type": "string", "readOnly": true }, "status": { "type": "string", "readOnly": true } }, "required": [ "category", "components", "id", "language", "name", "rejected_reason", "status" ] }, "ThreadControllerEnum": { "enum": [ "mba", "inbox" ], "type": "string", "description": "* `mba` - Meta Business Agent\n* `inbox` - Inbox" }, "Url": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string", "description": "URL description, like \"Homepage\", \"Social\" or \"Shop\", if provided. (Can be any string value)" } }, "required": [ "url" ] }, "User": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "readOnly": true }, "id": { "type": "integer", "readOnly": true }, "username": { "type": "string", "description": "Username that is used in combination with password during login.\n\nOnly alphanumeric characters are allowed (A-Z, a-z, 0-9)." }, "first_name": { "type": "string", "maxLength": 150 }, "last_name": { "type": "string", "maxLength": 150 }, "email": { "type": "string", "format": "email", "description": "E-mail address of this new user.\n\n" }, "profile": { "allOf": [ { "$ref": "#/components/schemas/UserProfile" } ], "description": "Optional field used to create app users and additional admin users" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/GroupMember" }, "readOnly": true, "description": "List of group objects the user belongs to (read-only)" }, "group_ids": { "type": "array", "items": { "type": "integer", "writeOnly": true }, "writeOnly": true, "description": "List of group IDs to assign to the user (write-only)" }, "permissions": { "$ref": "#/components/schemas/Permissions" }, "assigned_wa_ids": { "type": "array", "items": { "type": "string" }, "readOnly": true } }, "required": [ "assigned_wa_ids", "email", "groups", "id", "permissions", "url", "username" ] }, "UserAvailabilitySettings": { "type": "object", "properties": { "feature_set_enabled": { "type": "boolean", "description": "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)" } } }, "UserProfile": { "type": "object", "properties": { "role": { "allOf": [ { "$ref": "#/components/schemas/RoleEnum" } ], "description": "

Possible values:
* user (User) - can do everything that isn't marked as admin only in API documentation
* admin (Admin) - can use all available API endpoints and has Inbox admin panel access
* app (App integration) - can do everything regular users have access too, but has no access to inbox web frontend

\n\n* `user` - Regular user\n* `admin` - Admin\n* `app` - App integration" }, "is_available": { "type": "boolean", "description": "Manual status set by the user to indicate availability for communication." } } }, "VerticalEnum": { "enum": [ "Automotive", "Beauty, Spa and Salon", "Clothing and Apparel", "Education", "Entertainment", "Event Planning and Service", "Finance and Banking", "Food and Grocery", "Public Service", "Hotel and Lodging", "Medical and Health", "Non-profit", "Professional Services", "Shopping and Retail", "Travel and Transportation", "Restaurant", "Other" ], "type": "string", "description": "* `Automotive` - Automotive\n* `Beauty, Spa and Salon` - Beauty, Spa and Salon\n* `Clothing and Apparel` - Clothing and Apparel\n* `Education` - Education\n* `Entertainment` - Entertainment\n* `Event Planning and Service` - Event Planning and Service\n* `Finance and Banking` - Finance and Banking\n* `Food and Grocery` - Food and Grocery\n* `Public Service` - Public Service\n* `Hotel and Lodging` - Hotel and Lodging\n* `Medical and Health` - Medical and Health\n* `Non-profit` - Non-profit\n* `Professional Services` - Professional Services\n* `Shopping and Retail` - Shopping and Retail\n* `Travel and Transportation` - Travel and Transportation\n* `Restaurant` - Restaurant\n* `Other` - Other" }, "WabaError": { "type": "object", "properties": { "waba_payload": {}, "timestamp": { "type": "number", "format": "double" }, "waba_id": { "type": "string", "nullable": true, "title": "WhatsApp Message ID", "description": "WhatsApp Business API ID of the Message related to this error,if this error comes from an existing WhatsApp Message. Remember that if you're creating a Message and WhatsApp will return an user error (for example invalid template ID), then you will never see `waba_id` here, because Message was not created in WhatsApp. However, in that case you will still receive `getchat_id` for your reference.", "maxLength": 100 }, "getchat_id": { "type": "string", "nullable": true, "title": "Get.chat Message ID", "description": "Inbox internal ID of the Message that is related to this error. This field will be `null` in rare cases, so you should implement that. Examples are: 1. Fresh installation of a new inbox that is receiving error statuses from WhatsApp, but messages related to those errors are not present in the inbox - those messages were sent before user started using the inbox. 2. The inbox reached the quota limit and WhatsApp has sent an error status that is related to a message that was already removed from the inbox.", "maxLength": 100 } }, "required": [ "timestamp", "waba_payload" ] }, "WabaMessageStatuses": { "type": "object", "properties": { "sent": { "type": "number", "format": "double", "nullable": true }, "delivered": { "type": "number", "format": "double", "nullable": true }, "read": { "type": "number", "format": "double", "nullable": true } } }, "WabaPayloadContact": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/WabaPayloadProfile" }, "wa_id": { "type": "string" } }, "required": [ "profile", "wa_id" ] }, "WabaPayloadProfile": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "WabaWebhook": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "user": { "allOf": [ { "$ref": "#/components/schemas/ShortUser" } ], "readOnly": true }, "url": { "type": "string", "format": "uri", "description": "Remember to use `https://` URLs for your webhooks!\n\n**Note**: You can validate Webhook events by specifying a shared secret as a query parameter when you set the Webhook URL. Example: https://url?auth={shared_secret}." }, "on_incoming_message": { "type": "boolean", "description": "Call this Webhook on every new Message coming from WhatsApp to Inbox.
This is how WhatsApp webhooks are called." }, "on_outgoing_message": { "type": "boolean", "description": "Call this Webhook on every new Message sent from Inbox to WhatsApp.
You should use this setting when integrating a system in which you want to have complete copies of all your conversations." }, "on_assigned": { "type": "boolean", "description": "Call this Webhook when existing Chat is assigned to this User or a new Message is posted to the Chat already assigned to this User.

You should set this when integrating a bot with this Webhook.
This is similar to how human Users are notified by desktop notifications. " }, "on_message_echo": { "type": "boolean", "description": "Call this Webhook when a message is sent from your WhatsApp Business number via the 360dialog messaging API, outside the Inbox.
The webhook receives the original Cloud API \"message_echoes\" payload, so your integration can keep a complete copy of the conversation. Messages sent through the Inbox API are not echoed here - use \"on outgoing message\" for those." }, "headers": { "description": "Additional headers needed when calling a Webhook. Each header needs to be provided as a key-value pair in JSON format.
Useful for things like API keys with Authorization or other headers.

Example: {\"Authorization\": \"Token 1234567890qwertyuiop\"}" } }, "required": [ "id", "url", "user" ] }, "WhatsAppAccount": { "type": "object", "properties": { "phone_number": { "type": "string", "maxLength": 1000 }, "this_instance": { "type": "boolean", "description": "One customer can have multiple instances. This field denotes that this WA account is connected to this instance. DEPRECATED since MT 1.4: superseded by Tenant.whatsapp_account; kept (and still written by configure.py) for older-image compatibility and the read-only API field until a later cleanup release." } }, "required": [ "phone_number" ] } }, "securitySchemes": { "tokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "A user token, sent as `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.", "x-gitbook-prefix": "Token", "x-gitbook-token-placeholder": "YOUR_TOKEN" } } }, "servers": [ { "url": "https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/", "description": "Your Inbox address. Open the Inbox from the 360dialog Hub to see it.", "variables": { "YOUR_STACK_NAME": { "default": "your-stack", "description": "The first part of your Inbox address" } } } ], "tags": [ { "name": "Authorization", "description": "Endpoints related to Authorization" }, { "name": "WhatsApp Accounts", "description": "WhatsApp Accounts of your inbox" }, { "name": "Messages", "description": "You can receive and send WhatsApp messages using following endpoints." }, { "name": "Persons", "description": "WhatsApp Users who contacted your Inbox" }, { "name": "Contacts", "description": "WhatsApp Users' contact details\n\nThe Inbox does not keep or manage your contacts. Instead, you can connect your existing contact books or databases, using Contact Providers. \n\nWhen one or more Contact Providers are successfully connected to your inbox, you will be able to request related contact data from endpoints described here. \n\nIn the `/contacts/` section, there are also WhatsApp Business API provided endpoints like: verifying the Contact, blocking WhatsApp number, reporting WhatsApp user to Meta." }, { "name": "Chats", "description": "Existing conversations with WhatsApp Users" }, { "name": "Tags", "description": "A Tag is an object that is used when tagging Chats and Messages.\n\nA MessageTagging is a relationship object defining which Messages are tagged with which Tags.\n\nA ChatTagging is a relationship object defining which Chats are tagged with which Tags.\n\nA MessageTaggingEvent is a historical entry object defining which Messages were tagged with which Tags, by which User and when.\n\nA ChatTaggingEvent is a historical entry object defining which Chats were tagged with which Tags, by which User and when.\n\n" }, { "name": "Assignment", "description": "You can assign Chats to Users or Groups." }, { "name": "Saved Responses", "description": "You can keep simple text Saved Responses that your Inbox Users can use separately from Templates" }, { "name": "Templates", "description": "Message Templates management proxy" }, { "name": "Business Profile", "description": "Your WhatsApp Business Profile" }, { "name": "Media Files", "description": "\nJavaScript multipart/form-data Example To Create A Media File:\n```javascript\nconst file = document.querySelector(\"input[type=file]\").files[0];\n\nconst data = new FormData();\ndata.append('file_encoded', file);\n\nfetch('/api/v1/media/', {\n'method': 'POST',\n'headers': {\n 'Authorization': 'Token YOUR_TOKEN_HERE',\n},\n'body': data\n}).then(response => {\n return response.json();\n}).then(data => {\n console.log(data.file);\n}).catch((error) => {\n console.error('Error:', error);\n});\n```\n\nAbove POST request will produce a valid binary file upload HTTP request similar to:\n\n```http\n-----------------------------332889473834598984683101881237\nContent-Disposition: form-data; name=\"file_encoded\"; filename=\"img.jpg\"\nContent-Type: image/jpeg\n\n\n```\n\nAfter API will return with specified JSON data, line `console.log(data.file);` will print a direct URL\nto uploaded media file.\n " }, { "name": "Users", "description": "Inbox Users" }, { "name": "Groups", "description": "Groups of Inbox Users" }, { "name": "Webhooks", "description": "These API endpoints allow you to manage Webhooks.\n\nTo learn more about Webhooks' payload and when to expect them see Integration > WABA Webhook extension chapter" }, { "name": "Status", "description": "These API endpoints allow you to check the statuses of your Inbox and installed Plugins." }, { "name": "Errors", "description": "These API endpoints allow you to check the errors received from WABA" }, { "name": "Audit Logs", "description": "This API endpoint allows you to list logs of various events such as chats being assigned or resolved" } ], "security": [ { "tokenAuth": [] } ] }