{ "openapi": "3.1.0", "info": { "title": "Turbo Notify Public API", "description": "Turbo Notify Public API for WhatsApp messaging", "version": "1.0.0" }, "servers": [ { "url": "https://api.turbonotify.com" } ], "paths": { "/v1/events": { "get": { "tags": [ "Events" ], "summary": "List Events", "operationId": "list_events_v1_events_get", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by exact event type", "title": "Type" }, "description": "Filter by exact event type" }, { "name": "types[]", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, { "type": "null" } ], "description": "Filter by multiple event types", "title": "Types[]" }, "description": "Filter by multiple event types" }, { "name": "request_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by request ID", "title": "Request Id" }, "description": "Filter by request ID" }, { "name": "number_alias", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only events that carried this alias (`\"main\"` or the alias of an extra number) when they happened. A number you have renamed keeps its older events under its previous alias: filter by `number_id` to get all of them. Events that belong to no single number (`storage.*`) are left out when this filter is used.", "title": "Number Alias" }, "description": "Only events that carried this alias (`\"main\"` or the alias of an extra number) when they happened. A number you have renamed keeps its older events under its previous alias: filter by `number_id` to get all of them. Events that belong to no single number (`storage.*`) are left out when this filter is used." }, { "name": "number_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only events of the number with this id (`num_` followed by 32 characters), including the ones from before you renamed it. Combines with `number_alias`. Events that belong to no single number (`storage.*`) are left out when this filter is used. A malformed id answers 400 `invalid_number_id`.", "title": "Number Id" }, "description": "Only events of the number with this id (`num_` followed by 32 characters), including the ones from before you renamed it. Combines with `number_alias`. Events that belong to no single number (`storage.*`) are left out when this filter is used. A malformed id answers 400 `invalid_number_id`." }, { "name": "created[gte]", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Events created at or after this time", "title": "Created[Gte]" }, "description": "Events created at or after this time" }, { "name": "created[lte]", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Events created at or before this time", "title": "Created[Lte]" }, "description": "Events created at or before this time" }, { "name": "starting_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for forward pagination (event ID)", "title": "Starting After" }, "description": "Cursor for forward pagination (event ID)" }, { "name": "ending_before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for backward pagination (event ID)", "title": "Ending Before" }, "description": "Cursor for backward pagination (event ID)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of events to return", "default": 25, "title": "Limit" }, "description": "Number of events to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEventsResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages": { "get": { "tags": [ "Messages" ], "summary": "List Messages Flat", "description": "List messages for the main number inbox (cursor-paginated, newest first).", "operationId": "list_messages_flat_v1_messages_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "group_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only messages of this group (`grp_` followed by 32 hex characters). It must be a group of this number.", "examples": [ "grp_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Group Id" }, "description": "Only messages of this group (`grp_` followed by 32 hex characters). It must be a group of this number." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only messages this contact sent or received, including what they said in groups (`ct_` followed by 32 hex characters). It must be a contact of this number. Combine with `group_id` to read what one person said in one group.", "examples": [ "ct_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Contact Id" }, "description": "Only messages this contact sent or received, including what they said in groups (`ct_` followed by 32 hex characters). It must be a contact of this number. Combine with `group_id` to read what one person said in one group." }, { "name": "direction", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/MessageDirection" }, { "type": "null" } ], "description": "Only `inbound` (received) or only `outbound` (sent) messages.", "title": "Direction" }, "description": "Only `inbound` (received) or only `outbound` (sent) messages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageListResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Messages" ], "summary": "Send Message Flat", "description": "Send a message from the main number.", "operationId": "send_message_flat_v1_messages_post", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/quota": { "get": { "tags": [ "Messages" ], "summary": "Get Message Quota Flat", "description": "Return the message quota state for the main number.", "operationId": "get_message_quota_flat_v1_messages_quota_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageQuotaResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{message_id}/reply": { "post": { "tags": [ "Messages" ], "summary": "Reply To Message Flat", "description": "Reply to a message from the main number.\n\nThe recipient is inferred from the original message direction:\n- Outbound original → reply goes to the same contact / group.\n- Inbound original → reply goes to the sender.", "operationId": "reply_to_message_flat_v1_messages__message_id__reply_post", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyMessageRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{message_id}/react": { "post": { "tags": [ "Messages" ], "summary": "React To Message Flat", "description": "Add or remove a reaction on a message via the main number.\n\nThe message must belong to the main number.", "operationId": "react_to_message_flat_v1_messages__message_id__react_post", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReactionRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReactionResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{message_id}": { "get": { "tags": [ "Messages" ], "summary": "Get Message Details Flat", "description": "Retrieve the details of a message of the main number.", "operationId": "get_message_details_flat_v1_messages__message_id__get", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageDetailsResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{message_id}/status": { "get": { "tags": [ "Messages" ], "summary": "Get Message Status Flat", "description": "Get the delivery status of a message of the main number.", "operationId": "get_message_status_flat_v1_messages__message_id__status_get", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageStatusResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{message_id}/reactions": { "get": { "tags": [ "Messages" ], "summary": "Get Message Reactions Flat", "description": "List the reactions to a message of the main number.", "operationId": "get_message_reactions_flat_v1_messages__message_id__reactions_get", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageReactionsResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{message_id}/responses": { "get": { "tags": [ "Messages" ], "summary": "Get Message Responses Flat", "description": "List how the guests answered a calendar event of the main number.", "operationId": "get_message_responses_flat_v1_messages__message_id__responses_get", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageResponsesResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{message_id}/receipts": { "get": { "tags": [ "Messages" ], "summary": "Get Message Receipts Flat", "description": "List the delivery receipts of a message of the main number.", "operationId": "get_message_receipts_flat_v1_messages__message_id__receipts_get", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageReceiptsResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{message_id}/edit": { "post": { "tags": [ "Messages" ], "summary": "Edit Message Flat", "description": "Edit a message sent from the main number.\n\nA text message takes `{\"text\": ...}`. A calendar event takes the whole new\nevent (with `name`) and can be canceled with `canceled: true`. An image, video\nor document takes `{\"caption\": ...}`, the whole new caption. Any other pairing,\nand any other kind of message, is refused with `message_not_editable`.\nA text or a caption can only be changed within 15 minutes of sending it; a later\nchange is refused with `edit_window_expired`. The 15 minutes do not apply to a calendar event.", "operationId": "edit_message_flat_v1_messages__message_id__edit_post", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/EditTextMessageRequest" }, { "$ref": "#/components/schemas/EditCalendarMessageRequest" }, { "$ref": "#/components/schemas/EditCaptionMessageRequest" } ], "title": "Body" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditMessageResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/{message_id}/delete": { "post": { "tags": [ "Messages" ], "summary": "Delete Message Flat", "description": "Delete a message sent from the main number.", "operationId": "delete_message_flat_v1_messages__message_id__delete_post", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMessageResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/messages/read": { "post": { "tags": [ "Messages" ], "summary": "Mark As Read Flat", "description": "Mark a chat's (or WhatsApp Group's) unread inbound backlog as read\nfrom the main number.", "operationId": "mark_as_read_flat_v1_messages_read_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAsReadRequest" } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAsReadResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/typing-indicator": { "post": { "tags": [ "Messages" ], "summary": "Send Typing Indicator Flat", "description": "Send a typing indicator from the main number.", "operationId": "send_typing_indicator_flat_v1_typing_indicator_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTypingRequest" } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTypingResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List Contacts Flat", "description": "List contacts for the main number inbox.", "operationId": "list_contacts_flat_v1_contacts_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "phone", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" } }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ContactSource" }, { "type": "null" } ], "description": "Only contacts with this origin: `inbound` (the first message came from them), `outbound` (the first message went to them), `mention` (first seen in a mention) or `self` (one of your own numbers). Any other value is rejected with 422.", "title": "Source" }, "description": "Only contacts with this origin: `inbound` (the first message came from them), `outbound` (the first message went to them), `mention` (first seen in a mention) or `self` (one of your own numbers). Any other value is rejected with 422." }, { "name": "contacted_in_cycle", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "When true, only the contacts messaged through Turbo Notify in the main number's current billing cycle: the same contacts the contact quota's `used` counts. The count follows the billing cycle, not a rolling window.", "title": "Contacted In Cycle" }, "description": "When true, only the contacts messaged through Turbo Notify in the main number's current billing cycle: the same contacts the contact quota's `used` counts. The count follows the billing cycle, not a rolling window." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/quota": { "get": { "tags": [ "Contacts" ], "summary": "Get Contact Quota Flat", "description": "Return the contact quota state for the main number.", "operationId": "get_contact_quota_flat_v1_contacts_quota_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactQuotaResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/{contact_id}": { "get": { "tags": [ "Contacts" ], "summary": "Get Contact Flat", "description": "Retrieve a single contact of the main number.", "operationId": "get_contact_flat_v1_contacts__contact_id__get", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public contact identifier (ct_ + 32 hex chars)", "examples": [ "ct_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Contact Id" }, "description": "Public contact identifier (ct_ + 32 hex chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/{contact_id}/profile-picture": { "get": { "tags": [ "Contacts" ], "summary": "Get Contact Profile Picture Flat", "description": "Resolve the profile picture for a contact in the main number inbox.", "operationId": "get_contact_profile_picture_flat_v1_contacts__contact_id__profile_picture_get", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public contact identifier (ct_ + 32 hex chars)", "examples": [ "ct_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Contact Id" }, "description": "Public contact identifier (ct_ + 32 hex chars)" } ], "responses": { "302": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contacts/{contact_id}/refresh": { "post": { "tags": [ "Contacts" ], "summary": "Refresh Contact Flat", "description": "Queue a metadata refresh for a contact in the main number inbox.", "operationId": "refresh_contact_flat_v1_contacts__contact_id__refresh_post", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public contact identifier (ct_ + 32 hex chars)", "examples": [ "ct_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Contact Id" }, "description": "Public contact identifier (ct_ + 32 hex chars)" } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/groups": { "get": { "tags": [ "Groups" ], "summary": "List Groups Flat", "description": "List groups for the main number inbox.", "operationId": "list_groups_flat_v1_groups_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name" } }, { "name": "include_left", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Left" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupListResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/groups/{group_id}": { "get": { "tags": [ "Groups" ], "summary": "Get Group Flat", "description": "Retrieve a single group of the main number.", "operationId": "get_group_flat_v1_groups__group_id__get", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public group identifier (grp_ + 32 hex chars)", "examples": [ "grp_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Group Id" }, "description": "Public group identifier (grp_ + 32 hex chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/groups/{group_id}/picture": { "get": { "tags": [ "Groups" ], "summary": "Get Group Picture Flat", "description": "Resolve the profile picture of a group of the main number.", "operationId": "get_group_picture_flat_v1_groups__group_id__picture_get", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public group identifier (grp_ + 32 hex chars)", "examples": [ "grp_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Group Id" }, "description": "Public group identifier (grp_ + 32 hex chars)" } ], "responses": { "302": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers": { "get": { "tags": [ "Numbers" ], "summary": "List Numbers", "description": "List the numbers of your account: the main number first, then the extra numbers.\n\nEach number carries its `id`, which never changes when you rename the number.\nFilter with `status` to find the numbers in one state.", "operationId": "list_numbers_v1_numbers_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublicNumberStatus" }, { "type": "null" } ], "description": "Only numbers currently in this status, for example `disconnected` to find the numbers that need attention.", "title": "Status" }, "description": "Only numbers currently in this status, for example `disconnected` to find the numbers that need attention." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListExtraNumbersResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Numbers" ], "summary": "Add Extra Number", "description": "Add an extra number to the organization.\n\nAdding a number charges its activation to your payment method right away.\nAdditions are limited per organization over a rolling hour: past the\nlimit the request answers 429 `number_creation_rate_limited`, and the\n`Retry-After` header says how many seconds to wait.", "operationId": "add_extra_number_v1_numbers_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddExtraNumberRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddExtraNumberResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/main": { "get": { "tags": [ "Numbers" ], "summary": "Get Main Number", "operationId": "get_main_number_v1_numbers_main_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMainNumberResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}": { "get": { "tags": [ "Numbers" ], "summary": "Get Number Status", "description": "Retrieve one number by its alias or its id.\n\nAn extra number answers with its status and, while it is pairing, its code or QR code\nin `pairing`.\nThe id of the main number answers exactly like `GET /v1/numbers/main`.", "operationId": "get_number_status_v1_numbers__ref__get", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/GetExtraNumberStatusResponse" }, { "$ref": "#/components/schemas/GetMainNumberResponse" } ], "title": "Response Get Number Status V1 Numbers Ref Get" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Numbers" ], "summary": "Update Extra Number", "description": "Change the alias or the description of an extra number.\n\nThe number keeps its `id`, so anything you stored against it stays valid.\nThe main number cannot be changed: it answers 403 `main_number_update_not_allowed`.", "operationId": "update_extra_number_v1_numbers__ref__patch", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExtraNumberRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExtraNumberResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Numbers" ], "summary": "Remove Extra Number", "description": "Remove an extra number. Removing a number does not require disconnecting it.\n\nDepending on how it was used, the number is either removed right away with its\nactivation charge refunded, or its removal is scheduled for the end of the period\nyou already paid, with no refund. A scheduled number keeps its status and keeps\nworking until that date, and `scheduled_deletion_at` shows it. It is left out of\nthe next invoice. `cancel-deletion` keeps it. The response says which of the two\nhappened.", "operationId": "remove_extra_number_v1_numbers__ref__delete", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleExtraNumberDeletionResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/main/connect": { "post": { "tags": [ "Numbers" ], "summary": "Connect Main Number", "description": "Connect the main number.\n\nThe request is accepted at once and the number connects a few seconds later: read\n`GET /v1/numbers/main`, or wait for the `number.connected` event. A number that is\nalready connected or connecting answers 409 `already_connected` or `already_connecting`,\nand one that was never paired answers 422 `main_number_not_paired`.", "operationId": "connect_main_number_v1_numbers_main_connect_post", "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberConnectionResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/main/disconnect": { "post": { "tags": [ "Numbers" ], "summary": "Disconnect Main Number", "description": "Disconnect the main number and keep its link to the phone.\n\nThe request is accepted at once and the number disconnects a few seconds later: read\n`GET /v1/numbers/main`, or wait for the `number.disconnected` event. A number that is\nalready disconnected answers 409 `already_disconnected`.", "operationId": "disconnect_main_number_v1_numbers_main_disconnect_post", "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberConnectionResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/pair": { "post": { "tags": [ "Numbers" ], "summary": "Pair Extra Number", "description": "Start linking an extra number with a pairing code or a QR code.\n\nSend `method` (`pairing_code` by default, or `qr`). The answer comes right away:\nread the code or QR code from `GET /v1/numbers/{ref}`, in `pairing`. Calling this\nagain while the number is still pairing replaces the running attempt, so the\nperson gets a new code or a new QR code. The main number answers 403.", "operationId": "pair_extra_number_v1_numbers__ref__pair_post", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PairExtraNumberRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairExtraNumberResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/cancel-pairing": { "post": { "tags": [ "Numbers" ], "summary": "Cancel Extra Number Pairing", "operationId": "cancel_extra_number_pairing_v1_numbers__ref__cancel_pairing_post", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelExtraNumberPairingResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/connect": { "post": { "tags": [ "Numbers" ], "summary": "Connect Extra Number", "description": "Connect an extra number.\n\nThe request is accepted at once and the number connects a few seconds later: read\n`GET /v1/numbers/{ref}`, or wait for the `number.connected` event. A number that is\nalready connected or connecting answers 409 `already_connected` or `already_connecting`.\n\nThe main number answers 403 here, whether you address it as `main` or by its id:\nuse `POST /v1/numbers/main/connect` for it.\n\nA number whose removal is scheduled can be connected like any other. Connecting it\ndoes not change the removal date: use `cancel-deletion` to keep the number.", "operationId": "connect_extra_number_v1_numbers__ref__connect_post", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberConnectionResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/disconnect": { "post": { "tags": [ "Numbers" ], "summary": "Disconnect Extra Number", "description": "Disconnect an extra number.\n\nThe request is accepted at once and the number disconnects a few seconds later: read\n`GET /v1/numbers/{ref}`, or wait for the `number.disconnected` event. A number that is\nalready disconnected answers 409 `already_disconnected`.\n\nThe main number answers 403 here, whether you address it as `main` or by its id:\nuse `POST /v1/numbers/main/disconnect` for it.\n\nDisconnecting does not stop billing: a disconnected number is billed every cycle\nuntil you remove it. It does not change a scheduled removal either.", "operationId": "disconnect_extra_number_v1_numbers__ref__disconnect_post", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberConnectionResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/cancel-deletion": { "post": { "tags": [ "Numbers" ], "summary": "Cancel Extra Number Deletion", "description": "Cancel the scheduled removal of an extra number and keep it.\n\nThe number keeps its status. When the next invoice was already issued without the\nnumber, you are charged the amount from now to the end of the period it covers, and\nthe charge comes first: if your card is declined, the removal stays scheduled. A\ncharge can fail with 400 `no_payment_method`, 402 `payment_declined`, 402\n`payment_requires_authentication` or 503 `payment_gateway_unavailable`. A number\nthat is not scheduled for removal answers 400 `not_pending_deletion`.", "operationId": "cancel_extra_number_deletion_v1_numbers__ref__cancel_deletion_post", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelExtraNumberDeletionResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages": { "get": { "tags": [ "Numbers", "Messages" ], "summary": "List Messages", "description": "List messages for the inbox identified by ``alias`` (cursor-paginated, newest first).", "operationId": "list_messages_v1_numbers__ref__messages_get", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "group_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only messages of this group (`grp_` followed by 32 hex characters). It must be a group of this number.", "examples": [ "grp_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Group Id" }, "description": "Only messages of this group (`grp_` followed by 32 hex characters). It must be a group of this number." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only messages this contact sent or received, including what they said in groups (`ct_` followed by 32 hex characters). It must be a contact of this number. Combine with `group_id` to read what one person said in one group.", "examples": [ "ct_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Contact Id" }, "description": "Only messages this contact sent or received, including what they said in groups (`ct_` followed by 32 hex characters). It must be a contact of this number. Combine with `group_id` to read what one person said in one group." }, { "name": "direction", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/MessageDirection" }, { "type": "null" } ], "description": "Only `inbound` (received) or only `outbound` (sent) messages.", "title": "Direction" }, "description": "Only `inbound` (received) or only `outbound` (sent) messages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageListResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Numbers", "Messages" ], "summary": "Send Message", "description": "Send a message from the number identified by ``alias`` (``main`` or an extra alias).", "operationId": "send_message_v1_numbers__ref__messages_post", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/quota": { "get": { "tags": [ "Numbers", "Messages" ], "summary": "Get Message Quota Nested", "description": "Return the message quota state for the inbox identified by ``{ref}``.", "operationId": "get_message_quota_nested_v1_numbers__ref__messages_quota_get", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageQuotaResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/{message_id}/reply": { "post": { "tags": [ "Numbers", "Messages" ], "summary": "Reply To Message", "description": "Reply to a message from the number identified by ``alias``.\n\nThe recipient is inferred from the original message direction:\n- Outbound original → reply goes to the same contact / group.\n- Inbound original → reply goes to the sender.", "operationId": "reply_to_message_v1_numbers__ref__messages__message_id__reply_post", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyMessageRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/{message_id}/react": { "post": { "tags": [ "Numbers", "Messages" ], "summary": "React To Message", "description": "Add or remove a reaction from the number identified by ``alias``.\n\nThe target message must belong to the inbox identified by ``alias``; one\nthat belongs to a different number responds identically to one that does\nnot exist.", "operationId": "react_to_message_v1_numbers__ref__messages__message_id__react_post", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReactionRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReactionResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/{message_id}": { "get": { "tags": [ "Numbers", "Messages" ], "summary": "Get Message Details", "description": "Retrieve the full details of a message by its public ``msg_{hex}`` id.\n\nThe message must belong to the inbox identified by ``alias``; one that\nbelongs to a different number responds identically to one that does not\nexist, so a caller cannot enumerate messages from another number by\nguessing IDs.", "operationId": "get_message_details_v1_numbers__ref__messages__message_id__get", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageDetailsResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/{message_id}/status": { "get": { "tags": [ "Numbers", "Messages" ], "summary": "Get Message Status", "description": "Get delivery status for a sent message by its public message_id.", "operationId": "get_message_status_v1_numbers__ref__messages__message_id__status_get", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageStatusResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/{message_id}/reactions": { "get": { "tags": [ "Numbers", "Messages" ], "summary": "Get Message Reactions", "description": "List all active reactions to a message.", "operationId": "get_message_reactions_v1_numbers__ref__messages__message_id__reactions_get", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageReactionsResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/{message_id}/responses": { "get": { "tags": [ "Numbers", "Messages" ], "summary": "Get Message Responses", "description": "List how the guests answered a calendar event: going, not going or maybe.", "operationId": "get_message_responses_v1_numbers__ref__messages__message_id__responses_get", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageResponsesResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/{message_id}/receipts": { "get": { "tags": [ "Numbers", "Messages" ], "summary": "Get Message Receipts", "description": "List delivery receipt history for a message (status transitions, ASC).", "operationId": "get_message_receipts_v1_numbers__ref__messages__message_id__receipts_get", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageReceiptsResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/{message_id}/edit": { "post": { "tags": [ "Numbers", "Messages" ], "summary": "Edit Message", "description": "Edit a message you sent, by its public `msg_{hex32}` id.\n\nA text message takes `{\"text\": ...}`. A calendar event takes the whole new\nevent (with `name`) and can be canceled with `canceled: true`. An image, video\nor document takes `{\"caption\": ...}`, the whole new caption. Any other pairing,\nand any other kind of message, is refused with `message_not_editable`.\nA text or a caption can only be changed within 15 minutes of sending it; a later\nchange is refused with `edit_window_expired`. The 15 minutes do not apply to a calendar event.", "operationId": "edit_message_v1_numbers__ref__messages__message_id__edit_post", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/EditTextMessageRequest" }, { "$ref": "#/components/schemas/EditCalendarMessageRequest" }, { "$ref": "#/components/schemas/EditCaptionMessageRequest" } ], "title": "Body" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditMessageResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/{message_id}/delete": { "post": { "tags": [ "Numbers", "Messages" ], "summary": "Delete Message", "description": "Delete (revoke) a previously sent message by its public ``msg_{hex32}`` id.", "operationId": "delete_message_v1_numbers__ref__messages__message_id__delete_post", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public message identifier (msg_ + 32 hex chars)", "examples": [ "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Message Id" }, "description": "Public message identifier (msg_ + 32 hex chars)" }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMessageResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/typing-indicator": { "post": { "tags": [ "Numbers", "Messages" ], "summary": "Send Typing Indicator", "description": "Send a typing indicator from the number identified by ``alias``.\n\nThe sender is the number in the URL ``alias``. The ``from`` body field\nis not required, and when supplied it is ignored (the URL always wins).\n\nWith ``is_typing`` true, the number first appears online and the unread\nmessages it received in that conversation are marked as read, then after\na short random pause (between 0.3 and 1.5 seconds) the typing indicator shows,\nso it never shows over unread messages. With ``is_typing`` false only\nthe indicator is cleared and nothing is read.", "operationId": "send_typing_indicator_v1_numbers__ref__typing_indicator_post", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTypingRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTypingResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/messages/read": { "post": { "tags": [ "Numbers", "Messages" ], "summary": "Mark As Read", "description": "Mark a chat's (or WhatsApp Group's) unread inbound backlog as read\nfrom the number identified by ``alias``, independent of the\nautomatic mark-as-read that already accompanies send, reply, react,\nedit, delete and the start of the typing indicator (the number also\nappears online first, and goes back offline by itself a few minutes\nafter its last interaction). Useful for\na customer's own client that wants inbox parity (e.g. an unread\nbadge cleared by the user) without sending any WhatsApp message.\n\nThe sender is inferred from the URL ``alias``; there is no ``from``\nbody field.", "operationId": "mark_as_read_v1_numbers__ref__messages_read_post", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAsReadRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAsReadResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/contacts": { "get": { "tags": [ "Numbers", "Contacts" ], "summary": "List Contacts Nested", "description": "Return a cursor-paginated list of contacts for the inbox ``{ref}``.", "operationId": "list_contacts_nested_v1_numbers__ref__contacts_get", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "phone", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" } }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ContactSource" }, { "type": "null" } ], "description": "Only contacts with this origin: `inbound` (the first message came from them), `outbound` (the first message went to them), `mention` (first seen in a mention) or `self` (one of your own numbers). Any other value is rejected with 422.", "title": "Source" }, "description": "Only contacts with this origin: `inbound` (the first message came from them), `outbound` (the first message went to them), `mention` (first seen in a mention) or `self` (one of your own numbers). Any other value is rejected with 422." }, { "name": "contacted_in_cycle", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "When true, only the contacts messaged through Turbo Notify in this number's current billing cycle: the same contacts the contact quota's `used` counts. The count follows the billing cycle, not a rolling window.", "title": "Contacted In Cycle" }, "description": "When true, only the contacts messaged through Turbo Notify in this number's current billing cycle: the same contacts the contact quota's `used` counts. The count follows the billing cycle, not a rolling window." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/contacts/quota": { "get": { "tags": [ "Numbers", "Contacts" ], "summary": "Get Contact Quota Nested", "description": "Return the contact quota state for the inbox identified by ``{ref}``.", "operationId": "get_contact_quota_nested_v1_numbers__ref__contacts_quota_get", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactQuotaResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/contacts/{contact_id}": { "get": { "tags": [ "Numbers", "Contacts" ], "summary": "Get Contact Nested", "description": "Retrieve a single contact of the number identified by ``{ref}``.", "operationId": "get_contact_nested_v1_numbers__ref__contacts__contact_id__get", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public contact identifier (ct_ + 32 hex chars)", "examples": [ "ct_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Contact Id" }, "description": "Public contact identifier (ct_ + 32 hex chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/contacts/{contact_id}/profile-picture": { "get": { "tags": [ "Numbers", "Contacts" ], "summary": "Get Contact Profile Picture Nested", "description": "Resolve the profile picture of a contact of the number identified by ``{ref}``.", "operationId": "get_contact_profile_picture_nested_v1_numbers__ref__contacts__contact_id__profile_picture_get", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public contact identifier (ct_ + 32 hex chars)", "examples": [ "ct_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Contact Id" }, "description": "Public contact identifier (ct_ + 32 hex chars)" }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "302": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/contacts/{contact_id}/refresh": { "post": { "tags": [ "Numbers", "Contacts" ], "summary": "Refresh Contact Nested", "description": "Queue a WhatsApp metadata refresh for a contact in inbox ``{ref}``.", "operationId": "refresh_contact_nested_v1_numbers__ref__contacts__contact_id__refresh_post", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public contact identifier (ct_ + 32 hex chars)", "examples": [ "ct_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Contact Id" }, "description": "Public contact identifier (ct_ + 32 hex chars)" }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/groups": { "get": { "tags": [ "Numbers", "Groups" ], "summary": "List Groups Nested", "description": "Return a cursor-paginated list of groups for the inbox ``{ref}``.", "operationId": "list_groups_nested_v1_numbers__ref__groups_get", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name" } }, { "name": "include_left", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Left" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupListResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/groups/{group_id}": { "get": { "tags": [ "Numbers", "Groups" ], "summary": "Get Group Nested", "description": "Retrieve a single group belonging to this number.\n\nA group that belongs to a different number of the same organization is not\nreturned, even though the id is valid: ids are scoped to the number that\nlisted them.", "operationId": "get_group_nested_v1_numbers__ref__groups__group_id__get", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public group identifier (grp_ + 32 hex chars)", "examples": [ "grp_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Group Id" }, "description": "Public group identifier (grp_ + 32 hex chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/numbers/{ref}/groups/{group_id}/picture": { "get": { "tags": [ "Numbers", "Groups" ], "summary": "Get Group Picture Nested", "description": "Resolve the group's profile picture for inbox ``{ref}``.", "operationId": "get_group_picture_nested_v1_numbers__ref__groups__group_id__picture_get", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public group identifier (grp_ + 32 hex chars)", "examples": [ "grp_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Group Id" }, "description": "Public group identifier (grp_ + 32 hex chars)" }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number.", "examples": [ "main", "num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e" ], "title": "Ref" }, "description": "The number's alias (`main` for the main number, otherwise the alias of an extra number) or its id (`num_` followed by 32 characters). The id never changes, even when you rename the number." } ], "responses": { "302": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/organizations": { "get": { "tags": [ "Organizations" ], "summary": "List Organizations", "operationId": "list_organizations_v1_organizations_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationListResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/organizations/{organization_id}": { "get": { "tags": [ "Organizations" ], "summary": "Get Organization", "operationId": "get_organization_v1_organizations__organization_id__get", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Public organization identifier (org_ + 32 hex chars)", "examples": [ "org_0198d3c5a1b24d3e9f01a2b3c4d5e6f7" ], "title": "Organization Id" }, "description": "Public organization identifier (org_ + 32 hex chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "422": { "description": "The request has a value that is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/usage": { "get": { "tags": [ "Usage" ], "summary": "Get Usage", "operationId": "get_usage_v1_usage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/usage/messages": { "get": { "tags": [ "Usage" ], "summary": "Get Usage Messages", "operationId": "get_usage_messages_v1_usage_messages_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageMessagesResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "AddExtraNumberRequest": { "properties": { "alias": { "type": "string", "title": "Alias" }, "phone_number": { "type": "string", "title": "Phone Number", "description": "The phone of the number, in international format (for example `+5511988887777`)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "required": [ "alias", "phone_number" ], "title": "AddExtraNumberRequest" }, "AddExtraNumberResponse": { "properties": { "id": { "type": "string", "pattern": "^num_[0-9a-f]{32}$", "title": "Id", "description": "The number's id, for example `num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e`. It is assigned when the number is created and never changes, even when you rename the number, so it is the right key to store on your side. Use it in place of the alias in the paths under `/v1/numbers/{ref}`." }, "alias": { "type": "string", "title": "Alias" }, "phone_number": { "type": "string", "title": "Phone Number" }, "status": { "type": "string", "title": "Status" }, "created_at": { "type": "string", "title": "Created At" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "required": [ "id", "alias", "phone_number", "status", "created_at" ], "title": "AddExtraNumberResponse", "description": "The number just added. Fields in order: `id`, `alias`, `phone_number`, `status`,\n`created_at`, `description`." }, "CalendarResponseCountsPayload": { "properties": { "going": { "type": "integer", "title": "Going" }, "not_going": { "type": "integer", "title": "Not Going" }, "maybe": { "type": "integer", "title": "Maybe" }, "extra_guests": { "type": "integer", "title": "Extra Guests" } }, "additionalProperties": false, "type": "object", "required": [ "going", "not_going", "maybe", "extra_guests" ], "title": "CalendarResponseCountsPayload", "description": "How many guests gave each answer, and how many extra guests are expected." }, "CalendarResponseFromPayload": { "properties": { "contact_id": { "anyOf": [ { "type": "string", "pattern": "^ct_[0-9a-f]{32}$" }, { "type": "null" } ], "title": "Contact Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "number": { "type": "string", "title": "Number" } }, "additionalProperties": false, "type": "object", "required": [ "number" ], "title": "CalendarResponseFromPayload", "description": "The guest who answered." }, "CalendarResponseItem": { "properties": { "from": { "$ref": "#/components/schemas/CalendarResponseFromPayload" }, "response": { "type": "string", "enum": [ "going", "not_going", "maybe" ], "title": "Response" }, "extra_guests": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Extra Guests" }, "at": { "type": "string", "title": "At" } }, "additionalProperties": false, "type": "object", "required": [ "from", "response", "at" ], "title": "CalendarResponseItem", "description": "The latest answer of one guest." }, "CancelExtraNumberDeletionResponse": { "properties": { "status": { "type": "string", "title": "Status", "description": "The number's status, the same value `GET /v1/numbers/{ref}` returns." }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "When the number entered its current status. `null` while the number has no link yet." } }, "type": "object", "required": [ "status" ], "title": "CancelExtraNumberDeletionResponse", "description": "The number after its removal was cancelled. Fields in order: `status`, `at`." }, "CancelExtraNumberPairingResponse": { "properties": { "alias": { "type": "string", "title": "Alias" }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "alias", "status" ], "title": "CancelExtraNumberPairingResponse" }, "ContactListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ContactResponse" }, "type": "array", "title": "Data" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "has_more": { "type": "boolean", "title": "Has More", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "ContactListResponse", "description": "List of contacts plus an opaque next cursor.\n\n``cursor`` is the token to pass back as ``?cursor=...`` on the next\nrequest; ``null`` when there are no more contacts. ``has_more`` says the\nsame thing as a boolean (``true`` exactly when ``cursor`` is not\n``null``), to keep pagination loops simple." }, "ContactQuotaResponse": { "properties": { "used": { "type": "integer", "title": "Used" }, "quota": { "type": "integer", "title": "Quota" }, "remaining": { "type": "integer", "title": "Remaining" }, "cycle_start": { "type": "string", "title": "Cycle Start" }, "cycle_end": { "type": "string", "title": "Cycle End" }, "resets_at": { "type": "string", "title": "Resets At" }, "tier": { "type": "string", "title": "Tier" } }, "additionalProperties": false, "type": "object", "required": [ "used", "quota", "remaining", "cycle_start", "cycle_end", "resets_at", "tier" ], "title": "ContactQuotaResponse", "description": "A number's current contact-quota snapshot.\n\nThe quota counts the current billing cycle, from ``cycle_start`` to\n``cycle_end`` (the same shape as the message quota). ``resets_at``\nalways equals ``cycle_end``.\n\nThese three fields are UTC timestamps with second precision and a ``Z``\nsuffix, the same format used by the ``contact.quota.*`` webhook events\nand every other timestamp in the API (for example ``at`` on message\nresponses).\n\n.. code-block:: json\n\n {\n \"used\": 87,\n \"quota\": 1000,\n \"remaining\": 913,\n \"cycle_start\": \"2026-06-01T00:00:00Z\",\n \"cycle_end\": \"2026-07-01T00:00:00Z\",\n \"resets_at\": \"2026-07-01T00:00:00Z\",\n \"tier\": \"SOLO\"\n }" }, "ContactRefreshPayload": { "properties": { "requested_at": { "type": "string", "format": "date-time", "title": "Requested At" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At" }, "outcome": { "anyOf": [ { "type": "string", "enum": [ "updated", "unchanged", "number_not_connected", "unavailable" ] }, { "type": "null" } ], "title": "Outcome" } }, "additionalProperties": false, "type": "object", "required": [ "requested_at" ], "title": "ContactRefreshPayload", "description": "The last refresh you asked for on this contact.\n\n``completed_at`` and ``outcome`` stay ``null`` while the refresh runs." }, "ContactResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "number_alias": { "type": "string", "title": "Number Alias" }, "phone_number": { "type": "string", "pattern": "^\\+\\d{6,20}$", "title": "Phone Number" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "is_self": { "type": "boolean", "title": "Is Self", "default": false }, "first_messaged_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "First Messaged At" }, "last_interaction_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Interaction At" }, "verified_on_whatsapp_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Verified On Whatsapp At" }, "picture": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/ProfilePictureAvailable" }, { "$ref": "#/components/schemas/ProfilePicturePending" }, { "$ref": "#/components/schemas/ProfilePictureUnavailable" } ], "discriminator": { "propertyName": "kind", "mapping": { "available": "#/components/schemas/ProfilePictureAvailable", "pending": "#/components/schemas/ProfilePicturePending", "unavailable": "#/components/schemas/ProfilePictureUnavailable" } } }, { "type": "null" } ], "title": "Picture" }, "refresh": { "anyOf": [ { "$ref": "#/components/schemas/ContactRefreshPayload" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "additionalProperties": false, "type": "object", "required": [ "id", "number_alias", "phone_number", "created_at", "updated_at" ], "title": "ContactResponse", "description": "One contact.\n\n``picture`` says whether the contact's profile picture is available\n(``kind``: ``\"available\"`` or ``\"unavailable\"``); ``null`` when the\npicture has not been checked yet." }, "ContactSource": { "type": "string", "enum": [ "inbound", "outbound", "mention", "self" ], "title": "ContactSource", "description": "How a contact first appeared. It never changes afterwards.\n\nValues:\n inbound: the first message came from this contact.\n outbound: the first message was sent to this contact.\n mention: the contact was first seen in a mention (in a message\n received, sent from the phone or sent through the API).\n self: the contact is one of your own numbers (main or extra)." }, "ContactUsageSnapshot": { "properties": { "used": { "type": "integer", "title": "Used" }, "quota": { "type": "integer", "title": "Quota" }, "remaining": { "type": "integer", "title": "Remaining" }, "resets_at": { "type": "string", "title": "Resets At" }, "tier": { "type": "string", "title": "Tier" } }, "additionalProperties": false, "type": "object", "required": [ "used", "quota", "remaining", "resets_at", "tier" ], "title": "ContactUsageSnapshot", "description": "Contact-quota section of the usage response." }, "DeleteMessageResponse": { "properties": { "message_id": { "type": "string", "pattern": "^msg_[0-9a-f]{32}$", "title": "Message Id" }, "status": { "$ref": "#/components/schemas/MessageStatusPayload" } }, "type": "object", "required": [ "message_id", "status" ], "title": "DeleteMessageResponse" }, "EditCalendarMessageRequest": { "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "start_at": { "type": "string", "format": "date-time", "title": "Start At" }, "end_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "End At" }, "join_link": { "anyOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Join Link" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/SendLocationContent" }, { "type": "null" } ] }, "has_reminder": { "type": "boolean", "title": "Has Reminder", "default": false }, "reminder_offset_sec": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Reminder Offset Sec" }, "extra_guests_allowed": { "type": "boolean", "title": "Extra Guests Allowed", "default": false }, "canceled": { "type": "boolean", "title": "Canceled", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "name", "start_at" ], "title": "EditCalendarMessageRequest", "description": "Replace a calendar event you sent, or cancel it.\n\nSend the whole event, with the same fields as when you create one\n(`name` and `start_at` are required): whatever you leave out is removed\nfrom the event. Set `canceled` to `true` to cancel the event. It stays in\nthe chat marked as canceled and WhatsApp tells the guests.", "examples": [ { "description": "Numbers for the last quarter", "end_at": "2026-10-20T16:00:00-03:00", "name": "Quarterly review", "start_at": "2026-10-20T15:00:00-03:00" }, { "canceled": true, "name": "Quarterly review", "start_at": "2026-10-20T15:00:00-03:00" } ] }, "EditCaptionMessageRequest": { "properties": { "caption": { "type": "string", "maxLength": 1024, "minLength": 1, "title": "Caption", "description": "The new caption. Supports the same `@` mention tokens as text bodies (normalized digits, echoed in `mentions`)." } }, "additionalProperties": false, "type": "object", "required": [ "caption" ], "title": "EditCaptionMessageRequest", "description": "Replace the caption of an image, video or document you sent.\n\nThe file stays as it is; only the caption under it changes. Send the whole new\ncaption: it replaces the old one and cannot be empty.", "examples": [ { "caption": "Invoice for October, corrected total." } ] }, "EditMessageResponse": { "properties": { "message_id": { "type": "string", "pattern": "^msg_[0-9a-f]{32}$", "title": "Message Id" }, "status": { "$ref": "#/components/schemas/MessageStatusPayload" } }, "type": "object", "required": [ "message_id", "status" ], "title": "EditMessageResponse" }, "EditTextMessageRequest": { "properties": { "text": { "type": "string", "maxLength": 4096, "minLength": 1, "title": "Text" } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "EditTextMessageRequest", "description": "Replace the text of a text message you sent.", "examples": [ { "text": "The meeting moved to 4 PM." } ] }, "EventResponse": { "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "title": "Id" }, "type": { "type": "string", "title": "Type" }, "organization_id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$", "title": "Organization Id" }, "number_alias": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number Alias" }, "number_id": { "anyOf": [ { "type": "string", "pattern": "^num_[0-9a-f]{32}$" }, { "type": "null" } ], "title": "Number Id" }, "created_at": { "type": "string", "title": "Created At" }, "data": { "additionalProperties": true, "type": "object", "title": "Data" } }, "additionalProperties": false, "type": "object", "required": [ "id", "type", "organization_id", "created_at", "data" ], "title": "EventResponse", "description": "One event of the events list, with the same fields as the webhook.\n\n- ``id``: the event id (``evt_...``).\n- ``type``: the event type, for example ``message.received``.\n- ``organization_id``: your organization id (``org_...``).\n- ``number_alias``: the alias the number had when the event happened\n (``\"main\"`` or the alias of an extra number); absent on\n organization-wide events.\n- ``number_id``: the id of that number (``num_...``). It never changes,\n even when the number is renamed; absent where ``number_alias`` is.\n- ``created_at``: when the event was recorded (ISO 8601).\n- ``data``: the event payload, identical to the one the webhook delivers." }, "ExtraNumberStatusPayload": { "properties": { "status": { "type": "string", "title": "Status" }, "at": { "type": "string", "title": "At" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "type": "object", "required": [ "status", "at" ], "title": "ExtraNumberStatusPayload" }, "ExtraNumberSummaryResponse": { "properties": { "id": { "type": "string", "pattern": "^num_[0-9a-f]{32}$", "title": "Id", "description": "The number's id, for example `num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e`. It is assigned when the number is created and never changes, even when you rename the number, so it is the right key to store on your side. Use it in place of the alias in the paths under `/v1/numbers/{ref}`." }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "type": { "type": "string", "title": "Type", "default": "extra" }, "alias": { "type": "string", "title": "Alias" }, "number": { "type": "string", "title": "Number" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "status": { "$ref": "#/components/schemas/ExtraNumberStatusPayload" }, "scheduled_deletion_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scheduled Deletion At", "description": "When the number is removed, or `null` while no removal is scheduled. The number keeps its `status` and keeps working until then." } }, "type": "object", "required": [ "id", "alias", "number", "status" ], "title": "ExtraNumberSummaryResponse", "description": "One number of the account in the list.\n\nFields in order: `id`, `contact_id`, `name`, `type`, `alias`, `number`,\nthen `description`, `status` and `scheduled_deletion_at`." }, "GetExtraNumberStatusResponse": { "properties": { "id": { "type": "string", "pattern": "^num_[0-9a-f]{32}$", "title": "Id", "description": "The number's id, for example `num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e`. It is assigned when the number is created and never changes, even when you rename the number, so it is the right key to store on your side. Use it in place of the alias in the paths under `/v1/numbers/{ref}`." }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "type": { "type": "string", "const": "extra", "title": "Type", "default": "extra" }, "alias": { "type": "string", "title": "Alias" }, "number": { "type": "string", "title": "Number" }, "status": { "type": "string", "title": "Status" }, "at": { "type": "string", "title": "At" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "scheduled_deletion_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scheduled Deletion At", "description": "When the number is removed, or `null` while no removal is scheduled. The number keeps its `status` and keeps working until then." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "pairing": { "anyOf": [ { "$ref": "#/components/schemas/PairingInfo" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "alias", "number", "status", "at" ], "title": "GetExtraNumberStatusResponse", "description": "One extra number, with its status and, while pairing, its code or QR.\n\nFields in order: `id`, `contact_id`, `name`, `type`, `alias`, `number`,\n`status`, `at`, then `description`, `scheduled_deletion_at`, `reason` and\n`pairing`." }, "GetMainNumberResponse": { "properties": { "id": { "type": "string", "pattern": "^num_[0-9a-f]{32}$", "title": "Id", "description": "The number's id, for example `num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e`. It is assigned when the number is created and never changes, even when you rename the number, so it is the right key to store on your side. Use it in place of the alias in the paths under `/v1/numbers/{ref}`." }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "type": { "type": "string", "const": "main", "title": "Type" }, "alias": { "type": "string", "title": "Alias" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number" }, "status": { "type": "string", "title": "Status" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At" } }, "type": "object", "required": [ "id", "type", "alias", "status" ], "title": "GetMainNumberResponse", "description": "The main number of the account and its status.\n\nFields in order: `id`, `contact_id`, `name`, `type`, `alias`, `number`,\n`status`, `at`." }, "GetMessageDetailsResponse": { "properties": { "id": { "type": "string", "pattern": "^msg_[0-9a-f]{32}$", "title": "Id" }, "organization_id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$", "title": "Organization Id" }, "number_alias": { "type": "string", "title": "Number Alias" }, "number_id": { "type": "string", "pattern": "^num_[0-9a-f]{32}$", "title": "Number Id" }, "from": { "additionalProperties": true, "type": "object", "title": "From" }, "to": { "additionalProperties": true, "type": "object", "title": "To" }, "preview": { "type": "string", "title": "Preview" }, "content_expired": { "type": "boolean", "title": "Content Expired" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" }, "image": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Image" }, "video": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Video" }, "audio": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Audio" }, "document": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Document" }, "location": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Location" }, "calendar": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Calendar" }, "contact": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Contact" }, "sticker": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Sticker" }, "interactive": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Interactive" }, "replied": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Replied" }, "mentions": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Mentions" }, "content_type": { "type": "string", "title": "Content Type" }, "direction": { "type": "string", "title": "Direction" }, "channel": { "type": "string", "const": "whatsapp", "title": "Channel", "default": "whatsapp" }, "origin": { "type": "string", "enum": [ "tn", "native" ], "title": "Origin" }, "at": { "type": "string", "title": "At" }, "status": { "$ref": "#/components/schemas/MessageStatusPayload" } }, "additionalProperties": false, "type": "object", "required": [ "id", "organization_id", "number_alias", "number_id", "from", "to", "preview", "content_expired", "content_type", "direction", "origin", "at", "status" ], "title": "GetMessageDetailsResponse", "description": "One message, with the same fields as the ``message.*`` webhook events.\n\nCommon fields:\n- ``id``: the message id (``msg_...``).\n- ``organization_id``: your organization id (``org_...``).\n- ``number_alias``: the alias the number had when the message happened\n (``\"main\"`` or the alias of an extra number).\n- ``number_id``: the id of that number (``num_...``). It never changes,\n even when the number is renamed.\n- ``from``/``to``: sender and recipient; their shape depends on the\n direction.\n- ``preview``: the first characters of the message (up to 50). Like the\n content itself it expires with your plan's content retention period\n (1 hour by default, longer on plans that let you choose); it is then\n ``\"\"``.\n- ``content_expired``: ``true`` once the content passed that period and\n was deleted. The message itself is still returned for 12 months, and\n status, receipts, reactions, reply, react, edit and delete keep\n working; ``text`` is ``\"\"`` and every media or structured block is\n ``{\"kind\": \"unavailable\", \"reason\": \"expired\"}``.\n- ``content_type``: ``text``, ``image``, ``audio`` and so on.\n- ``direction``: ``\"outbound\"`` or ``\"inbound\"``.\n- ``channel``: always ``\"whatsapp\"``.\n- ``origin``: ``\"tn\"`` (sent through the API) or ``\"native\"`` (sent or\n received on WhatsApp itself). Always present, never ``null``.\n- ``at``: when the message happened on WhatsApp (ISO 8601). It does not\n change as the delivery state advances.\n- ``status``: ``{state, at, error}``. ``status.at`` is when the current\n delivery state was reached. ``error`` (``{code, message, hint}``) is\n present only when ``state`` is ``\"failed\"``.\n- ``mentions``: the ``@`` mentions found in the text or caption,\n in order, as ``[{contact_id?, name?, number}, ...]``; absent when the\n message mentions nobody. Kept after the content retention period ends.\n\nContent fields (one, matching ``content_type``):\n- ``text``: the full text, for ``content_type=\"text\"``.\n- ``image``, ``video``, ``audio``, ``document``, ``sticker``: the media,\n with a ``media`` block that says whether the file is available\n (``kind`` field).\n- ``location``: ``{latitude, longitude, name?, address?, ...}``.\n- ``calendar``: ``{name, start_at, ...}``.\n- ``interactive``: ``{interactive_type, body, header?, footer?, url_button}``.\n- ``replied``: ``{message_id, preview}``, on a reply.\n\nFor a reaction, ``content_type`` is ``\"text\"`` and ``text`` holds the\nemoji (``\"\"`` when the reaction was removed)." }, "GetMessageReactionsResponse": { "properties": { "message_id": { "type": "string", "pattern": "^msg_[0-9a-f]{32}$", "title": "Message Id" }, "reactions": { "items": { "$ref": "#/components/schemas/ReactionItem" }, "type": "array", "title": "Reactions" } }, "additionalProperties": false, "type": "object", "required": [ "message_id", "reactions" ], "title": "GetMessageReactionsResponse", "description": "Response for ``GET /v1/messages/{id}/reactions``." }, "GetMessageReceiptsResponse": { "properties": { "message_id": { "type": "string", "pattern": "^msg_[0-9a-f]{32}$", "title": "Message Id" }, "receipts": { "items": { "$ref": "#/components/schemas/ReceiptItem" }, "type": "array", "title": "Receipts" } }, "additionalProperties": false, "type": "object", "required": [ "message_id", "receipts" ], "title": "GetMessageReceiptsResponse", "description": "Response for ``GET /v1/messages/{id}/receipts``." }, "GetMessageResponsesResponse": { "properties": { "message_id": { "type": "string", "pattern": "^msg_[0-9a-f]{32}$", "title": "Message Id" }, "counts": { "$ref": "#/components/schemas/CalendarResponseCountsPayload" }, "responses": { "items": { "$ref": "#/components/schemas/CalendarResponseItem" }, "type": "array", "title": "Responses" } }, "additionalProperties": false, "type": "object", "required": [ "message_id", "counts", "responses" ], "title": "GetMessageResponsesResponse", "description": "Response for ``GET /v1/numbers/{ref}/messages/{id}/responses``.\n\n`responses` holds the latest answer of every guest, the most recent\nfirst. A guest who changed their mind appears once, with the new answer.", "examples": [ { "counts": { "extra_guests": 1, "going": 1, "maybe": 0, "not_going": 1 }, "message_id": "msg_0198d3c5a1b24d3e9f01a2b3c4d5e6f7", "responses": [ { "at": "2026-10-15T12:00:00Z", "extra_guests": 1, "from": { "contact_id": "ct_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e", "name": "Ana", "number": "5511999990001" }, "response": "going" }, { "at": "2026-10-15T11:00:00Z", "from": { "number": "5511999990002" }, "response": "not_going" } ] } ] }, "GetMessageStatusResponse": { "properties": { "message_id": { "type": "string", "pattern": "^msg_[0-9a-f]{32}$", "title": "Message Id" }, "status": { "$ref": "#/components/schemas/MessageStatusPayload" } }, "type": "object", "required": [ "message_id", "status" ], "title": "GetMessageStatusResponse" }, "GroupListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/GroupResponse" }, "type": "array", "title": "Data" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "has_more": { "type": "boolean", "title": "Has More", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "GroupListResponse", "description": "List of groups plus an opaque next-page cursor.\n\n``cursor`` is ``null`` when there are no more groups. ``has_more`` says\nthe same thing as a boolean (``true`` exactly when ``cursor`` is not\n``null``)." }, "GroupResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "number_alias": { "type": "string", "title": "Number Alias" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "participants_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Participants Count" }, "is_announce_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Announce Only" }, "is_locked": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Locked" }, "ephemeral_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Ephemeral Seconds" }, "is_active": { "type": "boolean", "title": "Is Active" }, "picture": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/ProfilePictureAvailable" }, { "$ref": "#/components/schemas/ProfilePicturePending" }, { "$ref": "#/components/schemas/ProfilePictureUnavailable" } ], "discriminator": { "propertyName": "kind", "mapping": { "available": "#/components/schemas/ProfilePictureAvailable", "pending": "#/components/schemas/ProfilePicturePending", "unavailable": "#/components/schemas/ProfilePictureUnavailable" } } }, { "type": "null" } ], "title": "Picture" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "additionalProperties": false, "type": "object", "required": [ "id", "number_alias", "is_active", "created_at", "updated_at" ], "title": "GroupResponse", "description": "One WhatsApp group the number belongs to." }, "InteractiveHeaderInput": { "properties": { "type": { "type": "string", "const": "text", "title": "Type" }, "text": { "type": "string", "maxLength": 60, "minLength": 1, "title": "Text" } }, "additionalProperties": false, "type": "object", "required": [ "type", "text" ], "title": "InteractiveHeaderInput", "description": "Header of an interactive message. Only a text header is supported." }, "InteractiveUrlButtonInput": { "properties": { "display_text": { "type": "string", "maxLength": 20, "minLength": 1, "title": "Display Text" }, "url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url" } }, "additionalProperties": false, "type": "object", "required": [ "display_text", "url" ], "title": "InteractiveUrlButtonInput", "description": "Single CTA-URL button (opens external link)." }, "ListEventsResponse": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/EventResponse" }, "type": "array", "title": "Data" }, "has_more": { "type": "boolean", "title": "Has More" } }, "additionalProperties": false, "type": "object", "required": [ "data", "has_more" ], "title": "ListEventsResponse", "description": "The response body of ``GET /v1/events``." }, "ListExtraNumbersResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExtraNumberSummaryResponse" }, "type": "array", "title": "Data" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "has_more": { "type": "boolean", "title": "Has More", "default": false } }, "type": "object", "required": [ "data" ], "title": "ListExtraNumbersResponse" }, "MarkAsReadRequest": { "properties": { "to": { "$ref": "#/components/schemas/OutboundRecipientInput" } }, "additionalProperties": false, "type": "object", "required": [ "to" ], "title": "MarkAsReadRequest" }, "MarkAsReadResponse": { "properties": { "operation_id": { "type": "string", "title": "Operation Id" }, "status": { "$ref": "#/components/schemas/ReadStatusPayload" } }, "type": "object", "required": [ "operation_id", "status" ], "title": "MarkAsReadResponse" }, "MessageDirection": { "type": "string", "enum": [ "outbound", "inbound" ], "title": "MessageDirection", "description": "Message direction." }, "MessageError": { "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hint" } }, "additionalProperties": false, "type": "object", "required": [ "code", "message" ], "title": "MessageError", "description": "Structured error for a failed message operation.\n\nThe same shape is used everywhere a failure is reported: the webhook\n``data.error`` of failed events and the ``status.error`` of the message\nendpoints (``GET /v1/messages/{id}``, ``GET .../status`` and the\nsend/edit/delete/reply responses). Present only when the message state\nis ``failed``; ``null`` or absent otherwise.\n\nFields:\n code: Stable machine-readable identifier. Branch on this value (for\n example ``media_fetch_failed``, ``unsupported_media_format``,\n ``reaction_lid_unavailable``). It is never translated or reworded.\n message: Human-readable summary of what went wrong.\n hint: Actionable remediation guidance. Omitted, never ``null``, when\n no guidance applies." }, "MessageListItem": { "properties": { "id": { "type": "string", "title": "Id" }, "organization_id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$", "title": "Organization Id" }, "number_alias": { "type": "string", "title": "Number Alias" }, "number_id": { "type": "string", "pattern": "^num_[0-9a-f]{32}$", "title": "Number Id" }, "from": { "additionalProperties": true, "type": "object", "title": "From" }, "to": { "additionalProperties": true, "type": "object", "title": "To" }, "direction": { "type": "string", "title": "Direction" }, "content_type": { "type": "string", "title": "Content Type" }, "channel": { "type": "string", "const": "whatsapp", "title": "Channel", "default": "whatsapp" }, "origin": { "type": "string", "enum": [ "tn", "native" ], "title": "Origin" }, "preview": { "type": "string", "title": "Preview" }, "content_expired": { "type": "boolean", "title": "Content Expired" }, "at": { "type": "string", "title": "At" }, "status": { "$ref": "#/components/schemas/MessageStatusPayload" } }, "additionalProperties": false, "type": "object", "required": [ "id", "organization_id", "number_alias", "number_id", "from", "to", "direction", "content_type", "origin", "preview", "content_expired", "at", "status" ], "title": "MessageListItem", "description": "Summary shape returned by ``GET /v1/numbers/{ref}/messages``.\n\nEach entry has every field the matching ``message.*`` event has, plus\n``content_expired`` and ``status``. The content itself (``text``, media,\nmentions) is on the single-message response.\n\n``content_expired`` is ``true`` once the content passed your plan's\ncontent retention period (``preview`` is then ``\"\"``); the message is\nstill listed for 12 months." }, "MessageListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MessageListItem" }, "type": "array", "title": "Data" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "has_more": { "type": "boolean", "title": "Has More", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MessageListResponse", "description": "Cursor-paginated list of messages for one number inbox." }, "MessageQuotaResponse": { "properties": { "used": { "type": "integer", "title": "Used" }, "quota": { "type": "integer", "title": "Quota" }, "remaining": { "type": "integer", "title": "Remaining" }, "cycle_start": { "type": "string", "title": "Cycle Start" }, "cycle_end": { "type": "string", "title": "Cycle End" }, "resets_at": { "type": "string", "title": "Resets At" }, "tier": { "type": "string", "title": "Tier" } }, "additionalProperties": false, "type": "object", "required": [ "used", "quota", "remaining", "cycle_start", "cycle_end", "resets_at", "tier" ], "title": "MessageQuotaResponse", "description": "A number's current message-quota snapshot.\n\nThe quota counts the current billing cycle, from ``cycle_start`` to\n``cycle_end``, exactly as the ``message.quota.*`` webhook events do.\n``resets_at`` always equals ``cycle_end``.\n\nThese three fields are UTC timestamps with second precision and a ``Z``\nsuffix, the same format used by the ``message.quota.*`` webhook events\nand every other timestamp in the API.\n\n.. code-block:: json\n\n {\n \"used\": 1234,\n \"quota\": 10000,\n \"remaining\": 8766,\n \"cycle_start\": \"2026-06-01T00:00:00Z\",\n \"cycle_end\": \"2026-07-01T00:00:00Z\",\n \"resets_at\": \"2026-07-01T00:00:00Z\",\n \"tier\": \"SOLO\"\n }" }, "MessageStatusPayload": { "properties": { "state": { "type": "string", "title": "State" }, "at": { "type": "string", "title": "At" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/MessageError" }, { "type": "null" } ] } }, "type": "object", "required": [ "state", "at" ], "title": "MessageStatusPayload" }, "MessageUsageSnapshot": { "properties": { "used": { "type": "integer", "title": "Used" }, "quota": { "type": "integer", "title": "Quota" }, "remaining": { "type": "integer", "title": "Remaining" }, "resets_at": { "type": "string", "title": "Resets At" }, "tier": { "type": "string", "title": "Tier" } }, "additionalProperties": false, "type": "object", "required": [ "used", "quota", "remaining", "resets_at", "tier" ], "title": "MessageUsageSnapshot", "description": "Message-quota section of the usage response." }, "NumberConnectionResponse": { "properties": { "alias": { "type": "string", "title": "Alias", "description": "The number's alias (`main` for the main number), also when you addressed the number by its `num_` id." }, "status": { "type": "string", "enum": [ "connecting", "disconnecting" ], "title": "Status", "description": "`connecting` when you asked the number to connect, `disconnecting` when you asked it to disconnect. It starts when the request is accepted and it is not the end result: the number reaches `connected` or `disconnected` a few seconds later. `disconnecting` appears only in this answer: `GET /v1/numbers/{ref}` keeps returning the previous status until the number is disconnected." }, "at": { "type": "string", "title": "At", "description": "When the request was accepted, in UTC: the moment `status` starts. The status that `GET /v1/numbers/{ref}` returns, and its own `at`, change when the number actually connects or disconnects." } }, "type": "object", "required": [ "alias", "status", "at" ], "title": "NumberConnectionResponse", "description": "The answer to connecting or disconnecting a number: the request was accepted (202).\n\nFields in order: `alias`, `status`, `at`. The number connects or disconnects a few\nseconds later: read `GET /v1/numbers/{ref}`, or wait for the `number.connected` and\n`number.disconnected` events." }, "NumberFamilyUsage": { "properties": { "used": { "type": "integer", "title": "Used" }, "quota": { "type": "integer", "title": "Quota" }, "remaining": { "type": "integer", "title": "Remaining" } }, "additionalProperties": false, "type": "object", "required": [ "used", "quota", "remaining" ], "title": "NumberFamilyUsage", "description": "``used``, ``quota`` and ``remaining`` of one quota on one number.\n\n``resets_at`` and ``tier`` are the same for every number of the\norganization, so they appear once, at the top level of the response." }, "NumberMessagesUsage": { "properties": { "alias": { "type": "string", "title": "Alias" }, "messages": { "$ref": "#/components/schemas/NumberFamilyUsage" } }, "additionalProperties": false, "type": "object", "required": [ "alias", "messages" ], "title": "NumberMessagesUsage", "description": "Per-number breakdown entry for ``GET /v1/usage/messages`` (messages only)." }, "NumberUsage": { "properties": { "alias": { "type": "string", "title": "Alias" }, "messages": { "$ref": "#/components/schemas/NumberFamilyUsage" }, "contacts": { "$ref": "#/components/schemas/NumberFamilyUsage" } }, "additionalProperties": false, "type": "object", "required": [ "alias", "messages", "contacts" ], "title": "NumberUsage", "description": "Per-number breakdown entry for ``GET /v1/usage`` (both families)." }, "OrganizationListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/OrganizationResponse" }, "type": "array", "title": "Data" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "has_more": { "type": "boolean", "title": "Has More", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "OrganizationListResponse", "description": "The organization of the API key, as a list.\n\nYour key belongs to one organization; exactly one is returned.\n``cursor`` is always ``null`` and ``has_more`` is always ``false``." }, "OrganizationResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "plan": { "type": "string", "title": "Plan" }, "locale": { "type": "string", "title": "Locale" }, "timezone": { "type": "string", "title": "Timezone" }, "suspended_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Suspended At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "plan", "locale", "timezone", "created_at", "updated_at" ], "title": "OrganizationResponse", "description": "The organization that owns the API key used in the request." }, "OutboundRecipientInput": { "properties": { "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number" }, "group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Id" }, "contact_id": { "anyOf": [ { "type": "string", "pattern": "^ct_[0-9a-f]{32}$" }, { "type": "null" } ], "title": "Contact Id" } }, "additionalProperties": false, "type": "object", "title": "OutboundRecipientInput", "description": "The recipient: a phone number, a group or a contact.\n\nSend exactly one of:\n- ``number``: the phone in E.164 format, for a one-to-one message.\n- ``group_id``: a group id (``grp_...``), to send to a WhatsApp group.\n- ``contact_id``: a contact id (``ct_...``); the message goes to that\n contact's phone.\n\nSending more than one, or none, is rejected with 422 ``invalid_recipient``." }, "OutboundSenderInput": { "properties": { "alias": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Alias" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number" } }, "additionalProperties": false, "type": "object", "title": "OutboundSenderInput", "description": "The sending number, given by ``alias`` or by ``number``.\n\nSend exactly one of them: ``alias`` (``\"main\"`` or the alias of an extra\nnumber) or ``number`` (the phone in E.164 format). Sending both, or\nneither, is rejected with 422." }, "PairExtraNumberRequest": { "properties": { "method": { "type": "string", "enum": [ "pairing_code", "qr" ], "title": "Method", "description": "How the person links the number: `pairing_code` (they type a code in WhatsApp, the default) or `qr` (they scan a QR code in WhatsApp).", "default": "pairing_code" } }, "additionalProperties": false, "type": "object", "title": "PairExtraNumberRequest", "description": "Optional body of the pairing request.\n\nAn extra number is paired with a pairing code or with a QR code, and\n`method` says which one you want. Leave the body out to get a pairing code.\n\n* `pairing_code` (default): the person types an 8 character code in\n WhatsApp (Linked devices, Link with phone number instead).\n* `qr`: the person scans a QR code in WhatsApp (Linked devices, Link a\n device).\n\nThe request answers right away. Read the result from `GET /v1/numbers/{ref}`,\nin `pairing` (`method`, `data`, `expires_at`). For `qr`, `data` is a PNG\ndata URI that you use as the `src` of an image. WhatsApp renews the QR code\nwhile the attempt lasts and the image renews itself, so read `pairing` again\ninstead of keeping the first image. Any other value of `method` answers 422." }, "PairExtraNumberResponse": { "properties": { "alias": { "type": "string", "title": "Alias" }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "alias", "status" ], "title": "PairExtraNumberResponse" }, "PairingInfo": { "properties": { "method": { "type": "string", "title": "Method", "description": "How the number is being linked: `pairing_code` or `qr`." }, "data": { "type": "string", "title": "Data", "description": "For `pairing_code`, the 8 character code the person types in WhatsApp. For `qr`, a PNG data URI to use as the `src` of an image, never as text. A QR image renews itself while the attempt lasts, so read it again instead of keeping the first one." }, "expires_at": { "type": "string", "title": "Expires At", "description": "When this attempt stops being usable, in UTC." } }, "type": "object", "required": [ "method", "data", "expires_at" ], "title": "PairingInfo", "description": "The code or QR code the person uses to link the number, while it is pairing." }, "ProfilePictureAvailable": { "properties": { "kind": { "type": "string", "const": "available", "title": "Kind", "default": "available" }, "url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url" }, "url_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Url Expires At" }, "hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hash" }, "fetched_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Fetched At" } }, "additionalProperties": false, "type": "object", "required": [ "url" ], "title": "ProfilePictureAvailable", "description": "Profile picture is accessible via a signed URL.\n\n``url_expires_at`` is set for temporary (signed) URLs and ``null`` for\npermanent public URLs. After a temporary URL expires, fetch the contact\nagain to get a fresh one instead of keeping the old URL.\n\n``hash`` is the hex-encoded SHA-256 of the picture bytes. It stays the\nsame when the same image is uploaded again, which helps to deduplicate.\n\n``fetched_at`` records when the picture was last fetched from\nWhatsApp, useful for freshness heuristics." }, "ProfilePicturePending": { "properties": { "kind": { "type": "string", "const": "pending", "title": "Kind", "default": "pending" }, "hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hash" } }, "additionalProperties": false, "type": "object", "title": "ProfilePicturePending", "description": "Profile picture upload to organization storage is in progress.\n\n``hash`` may be present when the SHA-256 of the fetched bytes is\nalready known while the upload is in progress." }, "ProfilePictureUnavailable": { "properties": { "kind": { "type": "string", "const": "unavailable", "title": "Kind", "default": "unavailable" }, "reason": { "type": "string", "enum": [ "no_storage", "upload_failed", "peer_has_none", "storage_circuit_open" ], "title": "Reason" }, "hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hash" }, "setup_hint": { "anyOf": [ { "$ref": "#/components/schemas/StorageSetupHint" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "reason" ], "title": "ProfilePictureUnavailable", "description": "Profile picture cannot be served.\n\n``reason`` vocabulary:\n\n* ``\"no_storage\"``: the organization has no object storage configured.\n ``setup_hint`` is always present.\n* ``\"upload_failed\"``: the upload failed after all retries.\n ``setup_hint`` is ``null``.\n* ``\"peer_has_none\"``: the contact has not set a profile picture.\n ``setup_hint`` is ``null`` (nothing to set up on your side).\n* ``\"storage_circuit_open\"``: uploads to the storage are paused after\n repeated failures. ``setup_hint`` is present.\n\n``setup_hint`` is present exactly when ``reason`` is ``\"no_storage\"`` or\n``\"storage_circuit_open\"``." }, "PublicNumberStatus": { "type": "string", "enum": [ "pending", "pairing", "inactive", "connecting", "connected", "disconnected", "reconnecting", "failed", "revoked" ], "title": "PublicNumberStatus", "description": "What a customer reads in a number's `status`." }, "ReactionFromPayload": { "properties": { "contact_id": { "anyOf": [ { "type": "string", "pattern": "^ct_[0-9a-f]{32}$" }, { "type": "null" } ], "title": "Contact Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "number": { "type": "string", "title": "Number" } }, "additionalProperties": false, "type": "object", "required": [ "number" ], "title": "ReactionFromPayload", "description": "The ``from`` party of a reaction item." }, "ReactionItem": { "properties": { "from": { "$ref": "#/components/schemas/ReactionFromPayload" }, "emoji": { "type": "string", "title": "Emoji" }, "at": { "type": "string", "title": "At" }, "direction": { "type": "string", "title": "Direction" } }, "additionalProperties": false, "type": "object", "required": [ "from", "emoji", "at", "direction" ], "title": "ReactionItem", "description": "A single active reaction to a message." }, "ReactionStatusPayload": { "properties": { "state": { "type": "string", "title": "State" }, "at": { "type": "string", "title": "At" } }, "type": "object", "required": [ "state", "at" ], "title": "ReactionStatusPayload" }, "ReadStatusPayload": { "properties": { "state": { "type": "string", "title": "State" }, "at": { "type": "string", "title": "At" } }, "type": "object", "required": [ "state", "at" ], "title": "ReadStatusPayload" }, "ReceiptFromPayload": { "properties": { "contact_id": { "anyOf": [ { "type": "string", "pattern": "^ct_[0-9a-f]{32}$" }, { "type": "null" } ], "title": "Contact Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number" } }, "additionalProperties": false, "type": "object", "title": "ReceiptFromPayload", "description": "The party who emitted a delivery/read receipt.\n\n``number`` is ``null`` when WhatsApp does not reveal the phone of the\nperson who acknowledged. The ``from`` object is still returned when\n``contact_id`` or ``name`` are known even without a phone number." }, "ReceiptItem": { "properties": { "from": { "anyOf": [ { "$ref": "#/components/schemas/ReceiptFromPayload" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "delivered", "read" ], "title": "Status" }, "at": { "type": "string", "title": "At" } }, "additionalProperties": false, "type": "object", "required": [ "status", "at" ], "title": "ReceiptItem", "description": "A single delivery-status transition event." }, "RefreshResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "queued" }, "requested_at": { "type": "string", "format": "date-time", "title": "Requested At" } }, "additionalProperties": false, "type": "object", "required": [ "requested_at" ], "title": "RefreshResponse" }, "ReplyMessageRequest": { "properties": { "content": { "oneOf": [ { "$ref": "#/components/schemas/SendTextContent" }, { "$ref": "#/components/schemas/SendLocationContent" }, { "$ref": "#/components/schemas/SendContactContent" }, { "$ref": "#/components/schemas/SendCalendarContent" }, { "$ref": "#/components/schemas/SendImageContent" }, { "$ref": "#/components/schemas/SendVideoContent" }, { "$ref": "#/components/schemas/SendAudioContent" }, { "$ref": "#/components/schemas/SendDocumentContent" }, { "$ref": "#/components/schemas/SendStickerContent" }, { "$ref": "#/components/schemas/SendInteractiveContent" } ], "title": "Content" } }, "additionalProperties": false, "type": "object", "required": [ "content" ], "title": "ReplyMessageRequest", "description": "``POST /v1/numbers/{ref}/messages/{message_id}/reply`` request body.\n\nBoth recipient (``to``) and sender number are inferred: the recipient\ncomes from the original message direction; the sender is the number in\nthe URL (its alias or its `num_` id). Only ``content`` is required." }, "ScheduleExtraNumberDeletionResponse": { "properties": { "scheduled_deletion_at": { "type": "string", "title": "Scheduled Deletion At", "description": "When the number is removed. The current time when it was removed right away; otherwise the end of its paid period. Until then the number keeps its status and keeps working, and `cancel-deletion` keeps it." }, "refund_eligible": { "type": "boolean", "title": "Refund Eligible", "description": "``true`` when the number was removed right away and its activation charge is refunded. ``false`` when the removal is scheduled for the end of the paid period, with no refund." }, "refund_amount_cents": { "type": "integer", "title": "Refund Amount Cents", "description": "Amount refunded to your payment method, in cents of your billing currency. 0 when there is no refund." }, "refund_status": { "anyOf": [ { "type": "string", "enum": [ "not_applicable", "succeeded", "failed" ] }, { "type": "null" } ], "title": "Refund Status", "description": "Outcome of the refund when the number was removed right away: `succeeded` (the amount is on its way back to your payment method), `not_applicable` (there was nothing to refund) or `failed` (the number is removed and our billing team completes the refund). Null when the removal is scheduled." } }, "type": "object", "required": [ "scheduled_deletion_at", "refund_eligible", "refund_amount_cents" ], "title": "ScheduleExtraNumberDeletionResponse", "description": "What removing the number did: removed right away with a refund, or scheduled." }, "SendAudioContent": { "properties": { "audio_url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Audio Url" }, "mime_type": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Mime Type" } }, "additionalProperties": false, "type": "object", "required": [ "audio_url" ], "title": "SendAudioContent", "description": "Send an audio file or voice note via a public URL.\n\nWhatsApp does not show captions on audio, so this content has no\n``caption`` field (a caption would be silently lost)." }, "SendCalendarContent": { "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "start_at": { "type": "string", "format": "date-time", "title": "Start At" }, "end_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "End At" }, "join_link": { "anyOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Join Link" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/SendLocationContent" }, { "type": "null" } ] }, "has_reminder": { "type": "boolean", "title": "Has Reminder", "default": false }, "reminder_offset_sec": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Reminder Offset Sec" }, "extra_guests_allowed": { "type": "boolean", "title": "Extra Guests Allowed", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "name", "start_at" ], "title": "SendCalendarContent", "description": "Schedule a calendar event as a WhatsApp event message.\n\n``start_at`` and ``end_at`` are timezone-aware ISO-8601 datetimes\n(values without a timezone are rejected)." }, "SendContactContent": { "properties": { "display_name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Display Name" }, "phones": { "items": { "$ref": "#/components/schemas/SendContactPhone" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Phones" }, "emails": { "items": { "$ref": "#/components/schemas/SendContactEmail" }, "type": "array", "maxItems": 10, "title": "Emails" }, "organization": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Organization" }, "title": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Title" }, "address": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Address" } }, "additionalProperties": false, "type": "object", "required": [ "display_name", "phones" ], "title": "SendContactContent", "description": "Share a contact card as a WhatsApp contact message.\n\nYou send the structured fields below and the vCard is built for you, so\nthe card always opens correctly in WhatsApp. You never write a vCard yourself." }, "SendContactEmail": { "properties": { "label": { "type": "string", "maxLength": 30, "title": "Label", "default": "Email" }, "address": { "type": "string", "format": "email", "title": "Address" } }, "additionalProperties": false, "type": "object", "required": [ "address" ], "title": "SendContactEmail", "description": "Single email entry of an outbound contact card." }, "SendContactPhone": { "properties": { "label": { "type": "string", "maxLength": 30, "title": "Label", "default": "Mobile" }, "number": { "type": "string", "maxLength": 30, "minLength": 3, "title": "Number" } }, "additionalProperties": false, "type": "object", "required": [ "number" ], "title": "SendContactPhone", "description": "Single phone entry of an outbound contact card." }, "SendDocumentContent": { "properties": { "document_url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Document Url" }, "mime_type": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Mime Type" }, "caption": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Caption", "description": "Optional caption. Supports the same `@` mention tokens as text bodies (normalized digits, echoed in `mentions`)." }, "filename": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Filename" } }, "additionalProperties": false, "type": "object", "required": [ "document_url" ], "title": "SendDocumentContent", "description": "Send a document (PDF, DOCX, XLSX, etc.) via a public URL." }, "SendImageContent": { "properties": { "image_url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Image Url" }, "mime_type": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Mime Type" }, "caption": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Caption", "description": "Optional caption. Supports the same `@` mention tokens as text bodies (normalized digits, echoed in `mentions`)." } }, "additionalProperties": false, "type": "object", "required": [ "image_url" ], "title": "SendImageContent", "description": "Send an image via a public URL. WhatsApp supports JPEG, PNG, WebP." }, "SendInteractiveContent": { "properties": { "interactive_type": { "type": "string", "const": "cta_url", "title": "Interactive Type" }, "body": { "type": "string", "maxLength": 1024, "minLength": 1, "title": "Body" }, "header": { "anyOf": [ { "$ref": "#/components/schemas/InteractiveHeaderInput" }, { "type": "null" } ] }, "footer": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ], "title": "Footer" }, "url_button": { "$ref": "#/components/schemas/InteractiveUrlButtonInput" } }, "additionalProperties": false, "type": "object", "required": [ "interactive_type", "body", "url_button" ], "title": "SendInteractiveContent", "description": "Interactive message with a call-to-action URL button.\n\n``interactive_type`` has a single accepted value today and ``url_button``\nis required. Only the call-to-action URL button is supported." }, "SendLocationContent": { "properties": { "latitude": { "type": "number", "maximum": 90.0, "minimum": -90.0, "title": "Latitude" }, "longitude": { "type": "number", "maximum": 180.0, "minimum": -180.0, "title": "Longitude" }, "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Name" }, "address": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Address" }, "url": { "anyOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Url" } }, "additionalProperties": false, "type": "object", "required": [ "latitude", "longitude" ], "title": "SendLocationContent", "description": "Pin a geographic point as a WhatsApp location message." }, "SendMessageRequest": { "properties": { "to": { "$ref": "#/components/schemas/OutboundRecipientInput" }, "quoted_message_id": { "anyOf": [ { "type": "string", "pattern": "^msg_[0-9a-f]{32}$" }, { "type": "null" } ], "title": "Quoted Message Id" }, "content": { "oneOf": [ { "$ref": "#/components/schemas/SendTextContent" }, { "$ref": "#/components/schemas/SendLocationContent" }, { "$ref": "#/components/schemas/SendContactContent" }, { "$ref": "#/components/schemas/SendCalendarContent" }, { "$ref": "#/components/schemas/SendImageContent" }, { "$ref": "#/components/schemas/SendVideoContent" }, { "$ref": "#/components/schemas/SendAudioContent" }, { "$ref": "#/components/schemas/SendDocumentContent" }, { "$ref": "#/components/schemas/SendStickerContent" }, { "$ref": "#/components/schemas/SendInteractiveContent" } ], "title": "Content" } }, "additionalProperties": false, "type": "object", "required": [ "to", "content" ], "title": "SendMessageRequest", "description": "``POST /v1/messages`` request body.\n\n``to`` identifies the recipient (a phone, a group or a contact).\n``content`` is the message itself; its kind is inferred from the fields\nyou send (see the content variants of this request).\n``quoted_message_id`` is optional: give a ``msg_...`` id to quote an\nexisting message without using the dedicated ``/reply`` endpoint.\n\nThe sending number is the one in the URL of\n``POST /v1/numbers/{ref}/messages`` (its alias or its `num_` id; the main\nnumber on ``POST /v1/messages``), so the body has no ``from`` field." }, "SendMessageResponse": { "properties": { "message_id": { "type": "string", "pattern": "^msg_[0-9a-f]{32}$", "title": "Message Id" }, "status": { "$ref": "#/components/schemas/MessageStatusPayload" } }, "additionalProperties": false, "type": "object", "required": [ "message_id", "status" ], "title": "SendMessageResponse" }, "SendReactionRequest": { "properties": { "reaction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reaction" } }, "additionalProperties": false, "type": "object", "title": "SendReactionRequest" }, "SendReactionResponse": { "properties": { "message_id": { "type": "string", "pattern": "^msg_[0-9a-f]{32}$", "title": "Message Id" }, "reaction_event_id": { "type": "string", "pattern": "^op_reaction_[0-9a-f]{12}$", "title": "Reaction Event Id" }, "status": { "$ref": "#/components/schemas/ReactionStatusPayload" } }, "type": "object", "required": [ "message_id", "reaction_event_id", "status" ], "title": "SendReactionResponse" }, "SendStickerContent": { "properties": { "sticker_url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Sticker Url" }, "mime_type": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Mime Type" } }, "additionalProperties": false, "type": "object", "required": [ "sticker_url" ], "title": "SendStickerContent", "description": "Send a sticker via a public URL (animated WebP recommended).\n\nWhatsApp does not show captions on stickers, so this content has no\n``caption`` field (a caption would be silently lost)." }, "SendTextContent": { "properties": { "text": { "type": "string", "maxLength": 4096, "minLength": 1, "title": "Text", "description": "Message body. `@` tokens (7-15 digits, e.g. `@5511990000001`) become real WhatsApp @mentions of that user: detected implicitly, normalized to canonical E.164 digits, and echoed in the message's `mentions` structure." } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "SendTextContent", "description": "Plain text message." }, "SendTypingRequest": { "properties": { "to": { "$ref": "#/components/schemas/OutboundRecipientInput" }, "is_typing": { "type": "boolean", "title": "Is Typing" }, "from": { "anyOf": [ { "$ref": "#/components/schemas/OutboundSenderInput" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "to", "is_typing" ], "title": "SendTypingRequest" }, "SendTypingResponse": { "properties": { "operation_id": { "type": "string", "title": "Operation Id" }, "status": { "$ref": "#/components/schemas/TypingStatusPayload" } }, "type": "object", "required": [ "operation_id", "status" ], "title": "SendTypingResponse" }, "SendVideoContent": { "properties": { "video_url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Video Url" }, "mime_type": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Mime Type" }, "caption": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Caption", "description": "Optional caption. Supports the same `@` mention tokens as text bodies (normalized digits, echoed in `mentions`)." } }, "additionalProperties": false, "type": "object", "required": [ "video_url" ], "title": "SendVideoContent", "description": "Send a video via a public URL. WhatsApp supports MP4, 3GPP." }, "StorageSetupHint": { "properties": { "setup_url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Setup Url" }, "docs_url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Docs Url" }, "message": { "type": "string", "title": "Message" } }, "additionalProperties": false, "type": "object", "required": [ "setup_url", "docs_url", "message" ], "title": "StorageSetupHint", "description": "How to fix the storage, sent with unavailable media or pictures.\n\nPresent only when ``reason`` is ``\"no_storage\"`` or\n``\"storage_circuit_open\"``: the cases where the organization can act\n(configure or fix its storage). It is absent on ``upload_failed``, a\none-off failure where the storage is configured and the hint would\nmislead.\n\nFields:\n setup_url: Deep link into the dashboard storage-setup flow.\n docs_url: Link to the public documentation page for BYO Object\n Storage configuration.\n message: Short English seed string suitable for display or\n further localisation (e.g. ``\"Configure your media storage\n to receive inbound media files.\"``)." }, "TypingStatusPayload": { "properties": { "state": { "type": "string", "title": "State" }, "at": { "type": "string", "title": "At" } }, "type": "object", "required": [ "state", "at" ], "title": "TypingStatusPayload" }, "UpdateExtraNumberRequest": { "properties": { "alias": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Alias" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "title": "UpdateExtraNumberRequest", "description": "Send only the fields you want to change.\n\nThe main number cannot be changed." }, "UpdateExtraNumberResponse": { "properties": { "id": { "type": "string", "pattern": "^num_[0-9a-f]{32}$", "title": "Id", "description": "The number's id, for example `num_0f8e2c4a6b1d4e7f9a3c5d7e9b1a3c5e`. It is assigned when the number is created and never changes, even when you rename the number, so it is the right key to store on your side. Use it in place of the alias in the paths under `/v1/numbers/{ref}`." }, "alias": { "type": "string", "title": "Alias" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "status": { "type": "string", "title": "Status" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "When the number entered its current status, the same value `GET /v1/numbers/{ref}` returns. Renaming or editing the number does not change it. `null` while the number has no link yet." }, "scheduled_deletion_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scheduled Deletion At", "description": "When the number is removed, or `null` while no removal is scheduled. The number keeps its `status` and keeps working until then." } }, "type": "object", "required": [ "id", "alias", "description", "status" ], "title": "UpdateExtraNumberResponse", "description": "The number after the change. Fields in order: `id`, `alias`, `description`,\n`status`, `at`, `scheduled_deletion_at`." }, "UsageMessagesResponse": { "properties": { "messages": { "$ref": "#/components/schemas/MessageUsageSnapshot" }, "numbers": { "items": { "$ref": "#/components/schemas/NumberMessagesUsage" }, "type": "array", "title": "Numbers" } }, "additionalProperties": false, "type": "object", "required": [ "messages", "numbers" ], "title": "UsageMessagesResponse", "description": "Subset returned by ``GET /v1/usage/messages``." }, "UsageResponse": { "properties": { "messages": { "$ref": "#/components/schemas/MessageUsageSnapshot" }, "contacts": { "$ref": "#/components/schemas/ContactUsageSnapshot" }, "numbers": { "items": { "$ref": "#/components/schemas/NumberUsage" }, "type": "array", "title": "Numbers" } }, "additionalProperties": false, "type": "object", "required": [ "messages", "contacts", "numbers" ], "title": "UsageResponse", "description": "Unified envelope returned by ``GET /v1/usage``." }, "ValidationErrorDetails": { "additionalProperties": false, "description": "Every field of the request that was rejected.", "properties": { "errors": { "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "title": "Errors", "type": "array" } }, "required": [ "errors" ], "title": "ValidationErrorDetails", "type": "object" }, "ValidationErrorItem": { "additionalProperties": false, "description": "One field of the request that was rejected.", "properties": { "field": { "description": "Where the problem is, as a dotted path that starts with the part of the request: `body.to.number`, `query.limit`.", "title": "Field", "type": "string" }, "message": { "description": "What is wrong with the value.", "title": "Message", "type": "string" }, "type": { "description": "A short machine-readable name for the kind of problem.", "title": "Type", "type": "string" } }, "required": [ "field", "message", "type" ], "title": "ValidationErrorItem", "type": "object" }, "ValidationErrorResponse": { "additionalProperties": false, "description": "Answer to a request that was understood but has a value that is not valid.", "properties": { "error": { "const": "validation_error", "title": "Error", "type": "string" }, "details": { "$ref": "#/components/schemas/ValidationErrorDetails" } }, "required": [ "error", "details" ], "title": "ValidationErrorResponse", "type": "object" } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key, created in the dashboard under Setup > API Keys. Send it on every request as `Authorization: Bearer `. A request without a valid key answers `401 not_authenticated`; a valid key without the operation's scope answers `403 insufficient_scope`." } } } }