{ "openapi": "3.0.3", "info": { "termsOfService": "https://www.vonage.com/legal/communications-apis/terms-of-use/", "contact": { "name": "Vonage Developer Relations", "email": "devrel@vonage.com", "url": "https://developer.vonage.com/" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.17.0", "title": "Messages API", "x-metaTitle": "Vonage Messages API (v1.0) Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Messages API (v1.0) in this reference guide. Learn more in Vonage's API documentation.", "description": "The Messages API consolidates and normalises exchanges across all messaging channels. It allows you to use a single API to interact with our various channels such as SMS, MMS, RCS, WhatsApp, Viber and Facebook Messenger. See [this note](https://developer.vonage.com/en/messages/technical-details#authentication) on authentication." }, "tags": [ { "name": "Messages", "description": "Send message Operation" } ], "servers": [ { "url": "https://{api-region}.nexmo.com/v1", "description": "API Server", "variables": { "api-region": { "description": "The region where the API request is sent.", "default": "api", "enum": [ "api", "api-eu", "api-us", "api-ap" ] } } } ], "paths": { "/messages": { "post": { "tags": [ "Messages" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "description": "Send a Message", "summary": "Send a message to the given channel", "operationId": "SendMessage", "requestBody": { "$ref": "#/components/requestBodies/SendMessageRequest" }, "responses": { "202": { "$ref": "#/components/responses/MessageAcceptedResponse" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/MessageUnprocessableResponse" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/messages/{message_uuid}": { "patch": { "tags": [ "Messages" ], "security": [ { "bearerAuth": [] } ], "summary": "Update a message for the given channel", "description": "This enpoint lets you update the status of outbound and/or inbound messages for certain channels. For example, you can revoke outbound messages or mark inbound messages as read.", "parameters": [ { "$ref": "#/components/parameters/MessageUUIDParameter" } ], "operationId": "UpdateMessage", "requestBody": { "$ref": "#/components/requestBodies/UpdateMessage" }, "responses": { "202": { "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "description": "Accepted." }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/MessageUnprocessableResponse" }, "429": { "$ref": "#/components/responses/429" } } } } }, "x-webhooks": { "message-status": { "{$request.body#/callback}": { "post": { "summary": "Message Status", "operationId": "message-status", "x-example-path": "/webhooks/message-status", "description": "The current status of a message that you have sent. This is a webhook that is triggered when the status of a message changes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/messageStatusSMS" }, { "$ref": "#/components/schemas/messageStatusMMS" }, { "$ref": "#/components/schemas/messageStatusRCS" }, { "$ref": "#/components/schemas/messageStatusWhatsApp" }, { "$ref": "#/components/schemas/messageStatusMessenger" }, { "$ref": "#/components/schemas/messageStatusViber" }, { "$ref": "#/components/schemas/messageStatusEmail" } ] } } } }, "responses": { "200": { "description": "Your server returns this code if it accepts the callback." } } } } }, "inbound-message": { "{$request.body#/callback}": { "post": { "summary": "Inbound Message", "operationId": "inbound-message", "x-example-path": "/webhooks/inbound-message", "description": "An inbound message from a customer to you.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/inboundMessageSMS" }, { "title": "MMS", "x-tab-id": "MMS", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/inboundMessageMMS" }, { "$ref": "#/components/schemas/Text" }, { "properties": { "text": { "type": "string", "description": "The text in the inbound message.", "maxLength": 640, "example": "This is sample text." } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageMMS" }, { "$ref": "#/components/schemas/Image" }, { "$ref": "#/components/schemas/multifileContent" }, { "properties": { "image": { "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL of the image attachment.\nSupports `.jpg`, `.jpeg`, `.png` and `.gif`.", "example": "https://example.com/image.jpg" }, "name": { "type": "string", "description": "The filename of the image file.", "example": "image.jpg" }, "caption": { "type": "string", "description": "Additional text to accompany the image.", "minLength": 1, "maxLength": 3000, "example": "Additional text to accompany the image." } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageMMS" }, { "$ref": "#/components/schemas/vCard" }, { "$ref": "#/components/schemas/multifileContent" }, { "properties": { "vcard": { "required": [ "url" ], "properties": { "url": { "type": "string", "example": "https://example.com/contact.vcf", "description": "Publicly accessible URL of the vCard attachment." }, "name": { "type": "string", "description": "The filename of the vCard file.", "example": "conatact.vcf" } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageMMS" }, { "$ref": "#/components/schemas/Audio" }, { "$ref": "#/components/schemas/multifileContent" }, { "properties": { "audio": { "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Publicly accessible URL of the audio attachment.", "minLength": 10, "maxLength": 2000, "example": "https://example.com/audio.mp3" }, "name": { "type": "string", "description": "The filename of the audio file.", "example": "audio.mp3" } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageMMS" }, { "$ref": "#/components/schemas/Video" }, { "$ref": "#/components/schemas/multifileContent" }, { "properties": { "video": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "description": "Publicly accessible URL of the video attachment.", "example": "https://example.com/video.mp4" }, "name": { "type": "string", "description": "The filename of the video file.", "example": "video.mp4" } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageMMS" }, { "$ref": "#/components/schemas/File" }, { "$ref": "#/components/schemas/multifileContent" }, { "properties": { "file": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Publicly accessible URL of the file attachment.", "example": "https://example.com/file.pdf" }, "name": { "type": "string", "description": "The filename of the file.", "example": "file.pdf" }, "caption": { "type": "string", "description": "Additional text to accompany the file.", "example": "Additional text to accompany the file." } } } } } ] } ] }, { "title": "RCS", "x-tab-id": "RCS", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/inboundMessageRCS" }, { "$ref": "#/components/schemas/Text" }, { "properties": { "text": { "type": "string", "description": "The text in the inbound message.", "maxLength": 3072, "example": "Inbound message text." } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageRCS" }, { "$ref": "#/components/schemas/Image" }, { "properties": { "image": { "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "description": "The URL for the image attachment on the Vonage media servers.", "example": "https://api-eu.nexmo.com/v3/media/6882bbe2-fe14-4e2f-910f-652beee058d4" }, "name": { "type": "string", "description": "The filename of the image file. Note: Android stickers are sent as `image` attachments.", "example": "image.jpg" } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageRCS" }, { "$ref": "#/components/schemas/Video" }, { "properties": { "video": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "description": "The URL for the video attachment on the Vonage media servers.", "example": "https://api-eu.nexmo.com/v3/media/6882bbe2-fe14-4e2f-910f-652beee058d4" }, "name": { "type": "string", "description": "The filename of the video file.", "example": "video.webm" } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageRCS" }, { "$ref": "#/components/schemas/Audio" }, { "properties": { "audio": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "description": "The URL for the audio attachment on the Vonage media servers.", "example": "https://api-eu.nexmo.com/v3/media/6882bbe2-fe14-4e2f-910f-652beee058d4" }, "name": { "type": "string", "description": "The filename of the audio file.", "example": "audio.mp3" } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageRCS" }, { "$ref": "#/components/schemas/File" }, { "properties": { "file": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "description": "The URL for the file attachment on the Vonage media servers.", "example": "https://api-eu.nexmo.com/v3/media/6882bbe2-fe14-4e2f-910f-652beee058d4" }, "name": { "type": "string", "description": "The filename of the file.", "example": "example.pdf" } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageRCS" }, { "$ref": "#/components/schemas/vCard" }, { "properties": { "vcard": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "description": "The URL for the vCard attachment on the Vonage media servers.", "example": "https://api-eu.nexmo.com/v3/media/6882bbe2-fe14-4e2f-910f-652beee058d4" }, "name": { "type": "string", "description": "The filename of the vCard file.", "example": "contact.vcf" } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageRCS" }, { "$ref": "#/components/schemas/Location" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageRCS" }, { "$ref": "#/components/schemas/Reply" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundMessageRCS" }, { "$ref": "#/components/schemas/Button" } ] } ] }, { "title": "WhatsApp", "x-tab-id": "WhatsApp", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/Text" }, { "properties": { "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" }, { "$ref": "#/components/schemas/WhatsAppReferralInfo" } ] } } }, { "$ref": "#/components/schemas/Self" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/Image" }, { "properties": { "image": { "properties": { "url": { "type": "string", "description": "Publicly accessible URL of the image attachment.", "example": "https://example.com/image.jpg" }, "name": { "type": "string", "description": "The filename of the image file.", "example": "image.jpg" } } }, "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" }, { "$ref": "#/components/schemas/WhatsAppReferralInfo" } ] } } }, { "$ref": "#/components/schemas/Self" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/Video" }, { "properties": { "video": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Publicly accessible URL of the video attachment.", "example": "https://example.com/video.mp4" }, "name": { "type": "string", "description": "The filename of the video file.", "example": "video.mp4" } } }, "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" }, { "$ref": "#/components/schemas/WhatsAppReferralInfo" } ] } } }, { "$ref": "#/components/schemas/Self" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/File" }, { "properties": { "file": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Publicly accessible URL of the file attachment.", "example": "https://example.com/file.pdf" }, "name": { "type": "string", "description": "The filename of the file.", "example": "file.pdf" } } }, "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" }, { "$ref": "#/components/schemas/WhatsAppReferralInfo" } ] } } }, { "$ref": "#/components/schemas/Self" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/Audio" }, { "properties": { "audio": { "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Publicly accessible URL of the audio attachment.", "example": "https://example.com/audio.mp3" }, "name": { "type": "string", "description": "The filename of the audio file.", "example": "audio.mp3" } } }, "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" }, { "$ref": "#/components/schemas/WhatsAppReferralInfo" } ] } } }, { "$ref": "#/components/schemas/Self" }, { "properties": { "audio": { "required": [ "url" ], "properties": { "url": { "minLength": 10, "maxLength": 2000 } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/Location" }, { "properties": { "location": { "properties": { "name": { "type": "string", "description": "The name of the location.", "example": "Vonage" }, "address": { "type": "string", "example": "23 Main St, Holmdel, NJ 07733, USA", "description": "Address of the location. Only displayed if `name` is present." }, "url": { "type": "string", "example": "https://www.vonage.com/", "description": "URL tied to the location, if provided by the sender." } } }, "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" }, { "$ref": "#/components/schemas/WhatsAppReferralInfo" } ] } } }, { "$ref": "#/components/schemas/Self" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/WhatsAppInboundContact" }, { "properties": { "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" }, { "$ref": "#/components/schemas/WhatsAppReferralInfo" } ] } } }, { "$ref": "#/components/schemas/Self" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/Reply" }, { "properties": { "reply": { "properties": { "description": { "type": "string", "example": "Select 9am appointment time", "description": "A description that may be added to the interactive options presented (available only on interactive lists)." } } }, "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" } ] } } }, { "$ref": "#/components/schemas/Self" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/WhatsAppInboundButton" }, { "properties": { "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" } ] } } }, { "$ref": "#/components/schemas/Self" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/Order" }, { "properties": { "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" }, { "$ref": "#/components/schemas/WhatsAppOrderInfo" } ] } } }, { "$ref": "#/components/schemas/Self" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/InboundSticker" }, { "properties": { "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" }, { "$ref": "#/components/schemas/WhatsAppReferralInfo" } ] } } }, { "$ref": "#/components/schemas/Self" } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/InboundReaction" }, { "properties": { "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" } ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/inboundWhatsAppMessageCommon" }, { "$ref": "#/components/schemas/Unsupported" }, { "properties": { "whatsapp": { "type": "object", "description": "WhatsApp-specific properties of the message.", "allOf": [ { "$ref": "#/components/schemas/WhatsAppSender" } ] } } } ] } ] }, { "title": "Messenger", "x-tab-id": "Messenger", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/InboundMessengerMessageCommon" }, { "$ref": "#/components/schemas/Text" } ] }, { "allOf": [ { "$ref": "#/components/schemas/InboundMessengerMessageCommon" }, { "$ref": "#/components/schemas/Image" } ] }, { "allOf": [ { "$ref": "#/components/schemas/InboundMessengerMessageCommon" }, { "$ref": "#/components/schemas/Video" } ] }, { "allOf": [ { "$ref": "#/components/schemas/InboundMessengerMessageCommon" }, { "$ref": "#/components/schemas/File" } ] }, { "allOf": [ { "$ref": "#/components/schemas/InboundMessengerMessageCommon" }, { "$ref": "#/components/schemas/Audio" }, { "properties": { "audio": { "required": [ "url" ], "properties": { "url": { "minLength": 10, "maxLength": 2000 } } } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/InboundMessengerMessageCommon" }, { "$ref": "#/components/schemas/Unsupported" } ] } ] }, { "title": "Viber", "x-tab-id": "Viber", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/InboundViberMessageCommon" }, { "$ref": "#/components/schemas/Text" } ] }, { "allOf": [ { "$ref": "#/components/schemas/InboundViberMessageCommon" }, { "$ref": "#/components/schemas/Image" } ] }, { "allOf": [ { "$ref": "#/components/schemas/InboundViberMessageCommon" }, { "$ref": "#/components/schemas/Video" } ] }, { "allOf": [ { "$ref": "#/components/schemas/InboundViberMessageCommon" }, { "$ref": "#/components/schemas/File" } ] } ] } ] } } } }, "responses": { "200": { "description": "Your server returns this code if it accepts the callback." } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "basicAuth": { "type": "http", "scheme": "basic" } }, "parameters": { "MessageUUIDParameter": { "name": "message_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID of the message to be updated" } }, "requestBodies": { "SendMessageRequest": { "description": "Send a Message.", "required": true, "x-show-example-request": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnyOutboundMessage" } } } }, "UpdateMessage": { "description": "Update a Message.", "required": true, "x-show-example-request": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "WhatsApp", "x-tab-id": "WhatsApp", "description": "WhatsApp", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "The status to set for the message. Setting the `status` of an **inbound** WhatsApp message to `read` indicates to the sender of the message that the message has been read (blue ticks are shown on that message in the WhatsApp UI). The `status` of an **outbound** WhatsApp message cannot be updated via this endpoint.", "example": "read", "enum": [ "read" ] }, "replying_indicator": { "type": "object", "description": "The replying indicator object.", "required": [ "show", "type" ], "properties": { "show": { "type": "boolean", "description": "Whether to show the replying indicator to the WhatsApp user.", "example": true }, "type": { "type": "string", "description": "The type of indicator to the WhatsApp user. The replying indicator will be dismissed once you respond, or after 25 seconds, whichever comes first. To prevent a poor user experience, only display a replying indicator if you are going to respond.", "example": "text", "enum": [ "text" ] } } } } }, { "title": "RCS", "x-tab-id": "RCS", "description": "RCS", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "The status to set for the message. - Setting the `status` of an **inbound** RCS message to `read` indicates to the sender of the message that the message has been read. - Setting the `status` of an **outbound** RCS message to `revoked` revokes that message if possible. See [RCS Message Revocation](/messages/guides/rcs/rcs-message-revocation) for more information.", "example": "revoked", "enum": [ "read", "revoked" ] } } } ] } } } } }, "responses": { "401": { "description": "Authentication failure", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "oneOf": [ { "description": "Missing or Invalid Credentials", "type": "object", "required": [ "type", "title", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/#unathorized" }, "title": { "type": "string", "description": "Generic error message", "example": "You did not provide correct credentials." }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Check that you're using the correct credentials, and that your account has this feature enabled" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, { "description": "Invalid Application Type", "type": "object", "required": [ "type", "title", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/#unprovisioned" }, "title": { "type": "string", "description": "Generic error message", "example": "The crendentials provided do not have access to the requested product" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Check your API key is correct and has been whitelisted" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } } ] } } } }, "402": { "description": "Payment Required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "MessageAcceptedResponse": { "description": "Accepted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "message_uuid" ], "properties": { "message_uuid": { "$ref": "#/components/schemas/MessageUuid" }, "workflow_id": { "$ref": "#/components/schemas/WorkflowId" } } } } } }, "MessageUnprocessableResponse": { "description": "Unprocessable Entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorInvalidJson" }, { "$ref": "#/components/schemas/ErrorChannel" }, { "$ref": "#/components/schemas/ErrorChannelParams" }, { "$ref": "#/components/schemas/ErrorSender" }, { "$ref": "#/components/schemas/ErrorRecipient" }, { "$ref": "#/components/schemas/ErrorMessageType" }, { "$ref": "#/components/schemas/ErrorMessageParams" }, { "$ref": "#/components/schemas/ErrorClientReference" } ] } } } } }, "schemas": { "AnyOutboundMessage": { "oneOf": [ { "title": "SMS", "x-tab-id": "SMS", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutboundSMSText" }, { "$ref": "#/components/schemas/Failover" } ] } ] }, { "title": "MMS", "x-tab-id": "MMS", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutboundMMSText" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundMMSImage" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundMMSvCard" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundMMSAudio" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundMMSVideo" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundMMSFile" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundMMSContent" }, { "$ref": "#/components/schemas/Failover" } ] } ] }, { "title": "RCS", "x-tab-id": "RCS", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutboundRCSText" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundRCSImage" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundRCSVideo" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundRCSFile" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundRCSCard" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundRCSCarousel" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundRCSCustom" }, { "$ref": "#/components/schemas/Failover" } ] } ] }, { "title": "WhatsApp", "x-tab-id": "WhatsApp", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutboundWhatsAppText" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundWhatsAppImage" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundWhatsAppAudio" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundWhatsAppVideo" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundWhatsAppFile" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundWhatsAppTemplate" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundWhatsAppSticker" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundWhatsAppReaction" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundWhatsAppCustom" }, { "$ref": "#/components/schemas/Failover" } ] } ] }, { "title": "Messenger", "x-tab-id": "Messenger", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutboundMessengerText" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundMessengerImage" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundMessengerAudio" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundMessengerVideo" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundMessengerFile" }, { "$ref": "#/components/schemas/Failover" } ] } ] }, { "title": "Viber", "x-tab-id": "Viber", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutboundViberText" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundViberImage" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundViberVideo" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundViberFile" }, { "$ref": "#/components/schemas/Failover" } ] } ] }, { "title": "Email (beta)", "x-tab-id": "Email", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutboundEmailText" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundEmailHtml" }, { "$ref": "#/components/schemas/Failover" } ] }, { "allOf": [ { "$ref": "#/components/schemas/OutboundEmailContent" }, { "$ref": "#/components/schemas/Failover" } ] } ] } ] }, "OutboundSMSText": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Text" }, { "properties": { "text": { "description": "The text of message to send; limited to 1000 characters. Unless unless `text` or `unicode` has been explicitly set as the value for `sms.encoding_type`, the Messages API automatically detects whether unicode characters are present in `text` and sends the message as appropriate as either a text or unicode SMS. For more information on concatenation and encoding please visit: [developer.vonage.com/messages/guides/sms/concatenation-and-encoding](https://developer.vonage.com/messages/guides/sms/concatenation-and-encoding).", "example": "Hello from Vonage" } } }, { "$ref": "#/components/schemas/channelOptionsSms" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMMSText": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Text" }, { "properties": { "text": { "type": "string", "description": "The text of message to send", "example": "Hello from Vonage" } } }, { "$ref": "#/components/schemas/channelOptionsMms" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMMSImage": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Image" }, { "properties": { "image": { "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL of the image attachment.\nSupports `.jpg`, `.jpeg`, `.png`, `.gif`, and `.bmp`, with a maximum size of 2MB.", "example": "https://example.com/image.jpg" }, "caption": { "type": "string", "description": "Additional text to accompany the image.", "minLength": 1, "maxLength": 3000, "example": "Additional text to accompany the image." } } } } }, { "$ref": "#/components/schemas/channelOptionsMms" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMMSvCard": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/vCard" }, { "properties": { "vcard": { "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL of the vCard attachment.\nSupports `.vcf` only.", "example": "https://example.com/contact.vcf" }, "caption": { "type": "string", "description": "Additional text to accompany the vCard.", "minLength": 1, "maxLength": 3000, "example": "Additional text to accompany the vCard." } } } } }, { "$ref": "#/components/schemas/channelOptionsMms" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMMSAudio": { "allOf": [ { "$ref": "#/components/schemas/Audio" }, { "properties": { "message_type": { "type": "string", "enum": [ "audio" ], "example": "audio", "description": "The type of message to send. You must provide `audio` in this field. Supports `.mp3`, `.amr`, `.midi`, `.wav`, and `.ac3`, with a maximum size of 2MB. For best device and network support .mp3 is recommended. Not supported for US short codes." }, "audio": { "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL of the audio attachment.", "example": "https://example.com/audio.mp3" }, "caption": { "type": "string", "description": "Additional text to accompany the audio file.", "minLength": 1, "maxLength": 3000, "example": "Additional text to accompany the audio file." } } } } }, { "$ref": "#/components/schemas/channelOptionsMms" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMMSVideo": { "allOf": [ { "$ref": "#/components/schemas/Video" }, { "properties": { "message_type": { "type": "string", "enum": [ "video" ], "example": "video", "description": "The type of message to send. You must provide `video` in this field. Supports `.mp4`, `.3pg`, `.avi`, and `.mpg`, with a maximum size of 2MB. For best device and network support .mp4 is recommended. Not supported for US short codes." }, "video": { "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL of the video attachment.", "example": "https://example.com/video.mp4" }, "caption": { "type": "string", "description": "Additional text to accompany the video file.", "minLength": 1, "maxLength": 3000, "example": "Additional text to accompany the video file." } } } } }, { "$ref": "#/components/schemas/channelOptionsMms" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMMSFile": { "allOf": [ { "$ref": "#/components/schemas/File" }, { "type": "object", "properties": { "file": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "description": "The publicly accessible URL of the file attachment.", "example": "https://example.com/file.pdf" }, "caption": { "type": "string", "description": "Additional text to accompany the file.", "minLength": 1, "maxLength": 3000, "example": "Please see the attached file." } } } } }, { "$ref": "#/components/schemas/channelOptionsMms" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMMSContent": { "allOf": [ { "$ref": "#/components/schemas/Content" }, { "$ref": "#/components/schemas/channelOptionsMms" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundRCSText": { "allOf": [ { "$ref": "#/components/schemas/Text" }, { "type": "object", "properties": { "text": { "description": "The text of the message to send. Limited to 3072 characters, including unicode." } } }, { "$ref": "#/components/schemas/channelOptionsRcsStandard" }, { "$ref": "#/components/schemas/outboundMessageCommon" }, { "type": "object", "properties": { "suggestions": { "type": "array", "description": "An array of suggestion objects to include with the message. You can include up to 11 suggestions per message.", "maxItems": 11, "items": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/RCSSuggestedReply" }, { "$ref": "#/components/schemas/RCSSuggestedActionDial" }, { "$ref": "#/components/schemas/RCSSuggestedActionViewLocation" }, { "$ref": "#/components/schemas/RCSSuggestedActionShareLocation" }, { "$ref": "#/components/schemas/RCSSuggestedActionOpenURL" }, { "$ref": "#/components/schemas/RCSSuggestedActionOpenURLWebview" }, { "$ref": "#/components/schemas/RCSSuggestedActionCreateCalendarEvent" } ] } } } } ] }, "OutboundRCSImage": { "allOf": [ { "$ref": "#/components/schemas/Image" }, { "type": "object", "properties": { "image": { "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "description": "The publicly accessible URL of the image attachment.\nSupported types are `.jpg`, `.jpeg`, `.gif`, and `.png`.", "example": "https://example.com/image.jpg" } } } } }, { "$ref": "#/components/schemas/channelOptionsRcsStandard" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundRCSVideo": { "allOf": [ { "$ref": "#/components/schemas/Video" }, { "type": "object", "properties": { "video": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "description": "The publicly accessible URL of the video attachment.\nSupported types are `.mp4`, `.m4v`, `.h263`, `.mpeg`, and `.webm`.", "example": "https://example.com/video.webm" } } } } }, { "$ref": "#/components/schemas/channelOptionsRcsStandard" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundRCSFile": { "allOf": [ { "$ref": "#/components/schemas/File" }, { "type": "object", "properties": { "file": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "description": "The publicly accessible URL of the file attachment.\nSupported types are `.pdf`", "example": "https://example.com/file.pdf" } } } } }, { "$ref": "#/components/schemas/channelOptionsRcsStandard" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundRCSCard": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Card", "x-tab-id": "Card", "type": "object", "required": [ "card" ], "properties": { "message_type": { "type": "string", "enum": [ "card" ], "example": "card", "description": "The type of message to send. You must provide `card` in this field" }, "card": { "$ref": "#/components/schemas/RCSCardProperties" } } }, { "$ref": "#/components/schemas/channelOptionsRcsStandard" }, { "$ref": "#/components/schemas/channelOptionsRcsRichCard" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundRCSCarousel": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Carousel", "x-tab-id": "Carousel", "type": "object", "required": [ "carousel" ], "properties": { "message_type": { "type": "string", "enum": [ "carousel" ], "example": "carousel", "description": "The type of message to send. You must provide `carousel` in this field" }, "carousel": { "type": "object", "required": [ "cards" ], "properties": { "cards": { "type": "array", "maxItems": 10, "minItems": 2, "description": "An array of card objects to include in the carousel. A carousel must contain between 2 and 10 cards. Cards in a carousel can only have a `VERTICAL` orientation.", "items": { "$ref": "#/components/schemas/RCSCardProperties" } } } }, "suggestions": { "type": "array", "description": "An array of suggestion objects to include with the message. You can include up to 11 suggestions per message.", "maxItems": 11, "items": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/RCSSuggestedReply" }, { "$ref": "#/components/schemas/RCSSuggestedActionDial" }, { "$ref": "#/components/schemas/RCSSuggestedActionViewLocation" }, { "$ref": "#/components/schemas/RCSSuggestedActionShareLocation" }, { "$ref": "#/components/schemas/RCSSuggestedActionOpenURL" }, { "$ref": "#/components/schemas/RCSSuggestedActionOpenURLWebview" }, { "$ref": "#/components/schemas/RCSSuggestedActionCreateCalendarEvent" } ] } } } }, { "$ref": "#/components/schemas/channelOptionsRcsStandard" }, { "$ref": "#/components/schemas/channelOptionsRcsCarousel" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundRCSCustom": { "allOf": [ { "$ref": "#/components/schemas/Custom" }, { "type": "object", "properties": { "custom": { "type": "object", "description": "A custom payload. The schema of a custom object can vary widely. This is a legacy option. We recommend using one of the other RCS message types where possible.", "additionalProperties": true } } }, { "$ref": "#/components/schemas/channelOptionsRcsStandard" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "RCSSuggestedReply": { "title": "Reply", "type": "object", "required": [ "type", "text", "postback_data" ], "properties": { "type": { "type": "string", "enum": [ "reply" ], "example": "reply", "description": "The type for the suggestion object. Must be `reply`." }, "text": { "type": "string", "maxLength": 25, "example": "Yes", "description": "The text to display on the suggestion chip." }, "postback_data": { "type": "string", "example": "question_1_yes", "description": "The data that will be sent back in the `reply.id` property of a `reply` message via the inbound message webhook when the user taps the suggestion chip." } } }, "RCSSuggestedActionStandardProperties": { "type": "object", "required": [ "text", "postback_data" ], "properties": { "text": { "type": "string", "maxLength": 25, "example": "Option 1", "description": "The text to display on the suggestion chip." }, "postback_data": { "type": "string", "example": "action_1", "description": "The data that will be sent back in the `button.payload` property of a `button` message via the inbound message webhook when the user taps the suggestion chip." } } }, "RCSSuggestedActionDial": { "title": "Action (Dial)", "allOf": [ { "$ref": "#/components/schemas/RCSSuggestedActionStandardProperties" }, { "type": "object", "required": [ "type", "phone_number" ], "properties": { "type": { "type": "string", "enum": [ "dial" ], "example": "dial", "description": "The type for the suggestion object. Must be `dial`." }, "phone_number": { "type": "string", "format": "e164", "pattern": "^\\+?[1-9]\\d{1,14}$", "example": "14155550100", "description": "The phone number to dial in E.164 format." }, "fallback_url": { "type": "string", "format": "url", "example": "https://example.com/contact", "description": "A URL to open if the device is unable to place a call." } } } ] }, "RCSSuggestedActionViewLocation": { "title": "Action (View Location)", "allOf": [ { "$ref": "#/components/schemas/RCSSuggestedActionStandardProperties" }, { "type": "object", "required": [ "type", "latitude", "longitude", "pin_label" ], "properties": { "type": { "type": "string", "enum": [ "view_location" ], "example": "view_location", "description": "The type for the suggestion object. Must be `view_location`." }, "latitude": { "type": "string", "example": "37.7749", "description": "The latitude of the location to view." }, "longitude": { "type": "string", "example": "-122.4194", "description": "The longitude of the location to view." }, "pin_label": { "type": "string", "example": "Vonage", "description": "A label to display on the location pin." }, "fallback_url": { "type": "string", "format": "url", "example": "https://example.com/contact", "description": "A URL to open if the device is unable to display a map." } } } ] }, "RCSSuggestedActionShareLocation": { "title": "Action (Share Location)", "allOf": [ { "$ref": "#/components/schemas/RCSSuggestedActionStandardProperties" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "share_location" ], "example": "share_location", "description": "The type for the suggestion object. Must be `share_location`." } } } ] }, "RCSSuggestedActionOpenURL": { "title": "Action (Open URL)", "allOf": [ { "$ref": "#/components/schemas/RCSSuggestedActionStandardProperties" }, { "type": "object", "required": [ "type", "url", "description" ], "properties": { "type": { "type": "string", "enum": [ "open_url" ], "example": "open_url", "description": "The type for the suggestion object. Must be `open_url`." }, "url": { "type": "string", "format": "url", "example": "https://example.com", "description": "The URL to open when the suggestion is tapped." }, "description": { "type": "string", "example": "A URL for the Example website.", "description": "A short description of the URL for accessibility purposes.", "minLength": 1, "maxLength": 500 } } } ] }, "RCSSuggestedActionOpenURLWebview": { "title": "Action (Open URL in Webview)", "allOf": [ { "$ref": "#/components/schemas/RCSSuggestedActionStandardProperties" }, { "type": "object", "required": [ "type", "url", "description" ], "properties": { "type": { "type": "string", "enum": [ "open_url_in_webview" ], "example": "open_url_in_webview", "description": "The type for the suggestion object. Must be `open_url_in_webview`." }, "url": { "type": "string", "format": "url", "example": "https://example.com", "description": "The URL to open when the suggestion is tapped." }, "description": { "type": "string", "example": "A URL for the Example website.", "description": "A short description of the URL for accessibility purposes.", "minLength": 1, "maxLength": 500 }, "view_mode": { "type": "string", "enum": [ "FULL", "TALL", "HALF" ], "example": "FULL", "description": "The mode for displaying the URL in the webview window." } } } ] }, "RCSSuggestedActionCreateCalendarEvent": { "title": "Action (Create Calendar Event)", "allOf": [ { "$ref": "#/components/schemas/RCSSuggestedActionStandardProperties" }, { "type": "object", "required": [ "type", "start_time", "end_time", "title", "description" ], "properties": { "type": { "type": "string", "enum": [ "create_calendar_event" ], "example": "create_calendar_event", "description": "The type for the suggestion object. Must be `create_calendar_event`." }, "start_time": { "type": "string", "format": "date-time", "example": "2023-01-01T10:00:00Z", "description": "The start time of the calendar event in ISO 8601 format." }, "end_time": { "type": "string", "format": "date-time", "example": "2023-01-01T11:00:00Z", "description": "The end time of the calendar event in ISO 8601 format." }, "title": { "type": "string", "example": "New Year Party", "description": "The title of the calendar event.", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "example": "Join us to celebrate the new year!", "description": "A description of the calendar event.", "minLength": 1, "maxLength": 500 }, "fallback_url": { "type": "string", "format": "url", "example": "https://www.google.com/calendar", "description": "A URL to open if the device is unable to display create a calendar event." } } } ] }, "RCSCardProperties": { "type": "object", "required": [ "title", "text", "media_url" ], "properties": { "title": { "type": "string", "maxLength": 200, "example": "Card Title", "description": "The title of the card." }, "text": { "type": "string", "maxLength": 2000, "example": "This is some text to display on the card.", "description": "The text to display on the card." }, "media_url": { "type": "string", "format": "url", "example": "https://example.com/image.jpg", "description": "The publicly accessible URL of the media attachment for the card.\nSupported media include images, videos, and PDFs." }, "media_description": { "type": "string", "example": "Image description for accessibility purposes.", "description": "A short description of the media for accessibility purposes." }, "media_height": { "type": "string", "enum": [ "SHORT", "MEDIUM", "TALL" ], "example": "SHORT", "description": "The height of the media element shown in the card.\n\nThis property only applies, and is **required**, when sending rich cards with a `card_orientation` of `VERTICAL`.\n" }, "thumbnail_url": { "type": "string", "format": "url", "example": "https://example.com/thumbnail.jpg", "description": "The publicly accessible URL of the thumbnail image for the card." }, "media_force_refresh": { "type": "boolean", "example": false, "description": "By default, media URLs are cached on the RCS platform for up to 60 days. Set this property to `true` to force the platform to fetch a fresh copy of the media from the provided URL." }, "suggestions": { "type": "array", "description": "An array of suggestion objects to include with the card. You can include up to 4 suggestions per card.", "maxItems": 4, "items": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/RCSSuggestedReply" }, { "$ref": "#/components/schemas/RCSSuggestedActionDial" }, { "$ref": "#/components/schemas/RCSSuggestedActionViewLocation" }, { "$ref": "#/components/schemas/RCSSuggestedActionShareLocation" }, { "$ref": "#/components/schemas/RCSSuggestedActionOpenURL" }, { "$ref": "#/components/schemas/RCSSuggestedActionOpenURLWebview" }, { "$ref": "#/components/schemas/RCSSuggestedActionCreateCalendarEvent" } ] } } } }, "OutboundWhatsAppText": { "allOf": [ { "$ref": "#/components/schemas/Text" }, { "properties": { "text": { "description": "The text of message to send; limited to 4096 characters, including unicode." } } }, { "$ref": "#/components/schemas/channelOptionsWhatsapp" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundWhatsAppImage": { "allOf": [ { "$ref": "#/components/schemas/Image" }, { "properties": { "image": { "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL of the image attachment.\nSupports `.jpg`, `.jpeg`, and `.png`.", "example": "https://example.com/image.jpg" }, "caption": { "type": "string", "description": "Additional text to accompany the image.", "minLength": 1, "maxLength": 3000, "example": "Additional text to accompany the image." } } } } }, { "$ref": "#/components/schemas/channelOptionsWhatsapp" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundWhatsAppAudio": { "allOf": [ { "$ref": "#/components/schemas/Audio" }, { "properties": { "audio": { "required": [ "url" ], "properties": { "url": { "description": "The URL of the audio attachment.\nSupports `.aac`, `.m4a`, `.amr`, `.mp3` and `.opus`.", "minLength": 10, "maxLength": 2000 } } } } }, { "$ref": "#/components/schemas/channelOptionsWhatsapp" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundWhatsAppVideo": { "allOf": [ { "$ref": "#/components/schemas/Video" }, { "properties": { "video": { "required": [ "url" ], "properties": { "url": { "description": "The URL of the video attachment.\nSupports `.mp4` and `.3gpp`. Note, only `H.264` video codec and `AAC` audio codec is supported." }, "caption": { "type": "string", "description": "Additional text to accompany the file.", "example": "Additional text." } } } } }, { "$ref": "#/components/schemas/channelOptionsWhatsapp" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundWhatsAppFile": { "allOf": [ { "$ref": "#/components/schemas/File" }, { "properties": { "file": { "required": [ "url" ], "properties": { "url": { "description": "The URL of the file attachment.\nSupports supports a wide range of attachments including `.zip`, `.csv` and `.pdf`." }, "caption": { "type": "string", "description": "Additional text to accompany the file.", "example": "Additional text." }, "name": { "type": "string", "description": "Optional parameter that specifies the name of the file being sent. If not included, the value for `caption` will be used as the file name. If neither `name` or `caption` are included, the file name will be parsed from the `url`.", "example": "file.pdf" } } } } }, { "$ref": "#/components/schemas/channelOptionsWhatsapp" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundWhatsAppTemplate": { "allOf": [ { "required": [ "message_type", "whatsapp" ] }, { "$ref": "#/components/schemas/Template" }, { "$ref": "#/components/schemas/channelOptionsWhatsapp" }, { "$ref": "#/components/schemas/outboundMessageCommon" }, { "properties": { "whatsapp": { "type": "object", "required": [ "locale" ], "properties": { "policy": { "type": "string", "example": "deterministic", "enum": [ "deterministic" ], "description": "Policy for resolving what language template to use. As of right now the only valid choice is `deterministic`." }, "locale": { "type": "string", "example": "en_US", "description": "The [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language of the template. See [the WhatsApp documentation](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages-) for supported languages." } } } } } ] }, "OutboundWhatsAppSticker": { "allOf": [ { "$ref": "#/components/schemas/Sticker" }, { "$ref": "#/components/schemas/channelOptionsWhatsapp" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundWhatsAppReaction": { "allOf": [ { "required": [ "context" ] }, { "$ref": "#/components/schemas/OutboundReaction" }, { "$ref": "#/components/schemas/channelOptionsWhatsapp" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundWhatsAppCustom": { "allOf": [ { "required": [ "message_type" ] }, { "$ref": "#/components/schemas/Custom" }, { "type": "object", "properties": { "custom": { "type": "object", "description": "A custom payload, which is passed directly to WhatsApp for certain features such as templates and interactive messages. The schema of a custom object can vary widely. [Read more about Custom Objects](https://developer.vonage.com/messages/concepts/custom-objects).", "additionalProperties": true } } }, { "$ref": "#/components/schemas/channelOptionsWhatsapp" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMessengerText": { "allOf": [ { "$ref": "#/components/schemas/Text" }, { "properties": { "text": { "description": "The text of message to send; limited to 640 characters, including unicode." } } }, { "$ref": "#/components/schemas/channelOptionsMessenger" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMessengerImage": { "allOf": [ { "$ref": "#/components/schemas/Image" }, { "properties": { "image": { "properties": { "url": { "type": "string", "description": "The URL of the image attachment.\nSupports `.jpg`, `.jpeg`, `.png` and `.gif`.", "example": "https://example.com/image.jpg" } } } } }, { "$ref": "#/components/schemas/channelOptionsMessenger" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMessengerAudio": { "allOf": [ { "$ref": "#/components/schemas/Audio" }, { "properties": { "audio": { "properties": { "url": { "description": "The URL of the audio attachment.\nOnly supports `.mp3` files", "minLength": 10, "maxLength": 2000 } } } } }, { "$ref": "#/components/schemas/channelOptionsMessenger" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMessengerVideo": { "allOf": [ { "$ref": "#/components/schemas/Video" }, { "properties": { "video": { "properties": { "url": { "description": "The URL of the video attachment.\nSupports `.mp4` files. Note, only `H.264` video codec and `AAC` audio codec is supported." } } } } }, { "$ref": "#/components/schemas/channelOptionsMessenger" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundMessengerFile": { "allOf": [ { "$ref": "#/components/schemas/File" }, { "properties": { "file": { "properties": { "url": { "description": "The URL of the file attachment.\nSupports a wide range of attachments including `.zip`, `.csv` and `.pdf`." } } } } }, { "$ref": "#/components/schemas/channelOptionsMessenger" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundViberText": { "allOf": [ { "$ref": "#/components/schemas/Text" }, { "properties": { "text": { "description": "The text of message to send; limited to 1000 characters, including unicode." } } }, { "$ref": "#/components/schemas/channelOptionsViberWithButton" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundViberImage": { "allOf": [ { "$ref": "#/components/schemas/Image" }, { "properties": { "image": { "properties": { "url": { "type": "string", "description": "The URL of the image attachment.\nSupports `.jpg`, `.jpeg`, and `.png`.", "example": "https://example.com/image.jpg" }, "caption": { "type": "string", "description": "A caption to accompany the image. Required if the message includes an action button.", "example": "Check out this new promotion" } } } } }, { "$ref": "#/components/schemas/channelOptionsViberWithButton" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundViberVideo": { "allOf": [ { "$ref": "#/components/schemas/Video" }, { "properties": { "video": { "properties": { "url": { "type": "string", "description": "The URL of the video attachment.", "example": "https://example.com/image.jpg" }, "caption": { "type": "string", "description": "Text caption to accompany message.", "example": "Check out this new video" }, "thumb_url": { "type": "string", "maxLength": 1000, "description": "URL to an image file for a thumbnail preview of the video.", "example": "https://example.com/file1.jpg" } }, "required": [ "url", "duration", "file_size", "thumb_url" ] } } }, { "$ref": "#/components/schemas/channelOptionsViberVideo" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundViberFile": { "allOf": [ { "$ref": "#/components/schemas/File" }, { "properties": { "file": { "description": "An object containing details of the file to be sent. Note: allowed file types are `.doc,` `.docx`, `.rtf`, `.dot`, `.dotx`, `.odt`, `.odf`, `.fodt`, `.txt`, `.info`, `.pdf`, `.xps`, `.pdax`, `.eps`, `.xls`, `.xlsx`, `.ods`, `.fods`, `.csv`, `.xlsm`, `.xltx`. Maximum file size is 200MB", "properties": { "url": { "type": "string", "description": "The URL for the file attachment *or* the path for the location of the file attachement. If `name` is included, can just be the path. If `name` is not included, must include the filename and extension.", "example": "https://example.com/files/" }, "name": { "type": "string", "maxLength": 25, "description": "The name and extension of the file.", "example": "example.pdf" } } } } }, { "$ref": "#/components/schemas/channelOptionsViber" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundEmailText": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Text" }, { "properties": { "text": { "description": "The text of message to send." } } }, { "$ref": "#/components/schemas/channelOptionsEmail" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundEmailHtml": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/HTML" }, { "properties": { "html": { "type": "object", "required": [ "body" ], "description": "The content and structure of the HTML email message.", "properties": { "body": { "type": "string", "description": "The HTML content of the email message.", "example": "

Welcome to our service

We're glad to have you on board!

" } } } } }, { "$ref": "#/components/schemas/channelOptionsEmail" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "OutboundEmailContent": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/EmailContent" }, { "properties": { "content": { "type": "array", "description": "An array of objects containing the details of the email content to send.", "items": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/EmailContentText" }, { "$ref": "#/components/schemas/EmailContentHtml" } ] } } } }, { "$ref": "#/components/schemas/channelOptionsEmail" }, { "$ref": "#/components/schemas/outboundMessageCommon" } ] }, "Failover": { "type": "object", "properties": { "failover": { "type": "array", "description": "An array of objects containing the details of the failover messages to send if the primary message fails. The failover messages are sent in the order they are defined in the array. The first message is sent as a fallback if the primary message is `rejected`, and so on.", "items": { "type": "object", "anyOf": [ { "title": "SMS", "x-tab-id": "SMS", "oneOf": [ { "$ref": "#/components/schemas/OutboundSMSText" } ] }, { "title": "MMS", "x-tab-id": "MMS", "oneOf": [ { "$ref": "#/components/schemas/OutboundMMSText" }, { "$ref": "#/components/schemas/OutboundMMSImage" }, { "$ref": "#/components/schemas/OutboundMMSvCard" }, { "$ref": "#/components/schemas/OutboundMMSAudio" }, { "$ref": "#/components/schemas/OutboundMMSVideo" }, { "$ref": "#/components/schemas/OutboundMMSFile" }, { "$ref": "#/components/schemas/OutboundMMSContent" } ] }, { "title": "RCS", "x-tab-id": "RCS", "oneOf": [ { "$ref": "#/components/schemas/OutboundRCSText" }, { "$ref": "#/components/schemas/OutboundRCSImage" }, { "$ref": "#/components/schemas/OutboundRCSVideo" }, { "$ref": "#/components/schemas/OutboundRCSFile" }, { "$ref": "#/components/schemas/OutboundRCSCard" }, { "$ref": "#/components/schemas/OutboundRCSCarousel" }, { "$ref": "#/components/schemas/OutboundRCSCustom" } ] }, { "title": "WhatsApp", "x-tab-id": "WhatsApp", "oneOf": [ { "$ref": "#/components/schemas/OutboundWhatsAppText" }, { "$ref": "#/components/schemas/OutboundWhatsAppImage" }, { "$ref": "#/components/schemas/OutboundWhatsAppAudio" }, { "$ref": "#/components/schemas/OutboundWhatsAppVideo" }, { "$ref": "#/components/schemas/OutboundWhatsAppFile" }, { "$ref": "#/components/schemas/OutboundWhatsAppTemplate" }, { "$ref": "#/components/schemas/OutboundWhatsAppSticker" }, { "$ref": "#/components/schemas/OutboundWhatsAppReaction" }, { "$ref": "#/components/schemas/OutboundWhatsAppCustom" } ] }, { "title": "Messenger", "x-tab-id": "Messenger", "oneOf": [ { "$ref": "#/components/schemas/OutboundMessengerText" }, { "$ref": "#/components/schemas/OutboundMessengerImage" }, { "$ref": "#/components/schemas/OutboundMessengerAudio" }, { "$ref": "#/components/schemas/OutboundMessengerVideo" }, { "$ref": "#/components/schemas/OutboundMessengerFile" } ] }, { "title": "Viber", "x-tab-id": "Viber", "oneOf": [ { "$ref": "#/components/schemas/OutboundViberText" }, { "$ref": "#/components/schemas/OutboundViberImage" }, { "$ref": "#/components/schemas/OutboundViberVideo" }, { "$ref": "#/components/schemas/OutboundViberFile" } ] }, { "title": "Email (beta)", "x-tab-id": "Email", "oneOf": [ { "$ref": "#/components/schemas/OutboundEmailText" }, { "$ref": "#/components/schemas/OutboundEmailHtml" }, { "$ref": "#/components/schemas/OutboundEmailContent" } ] } ] } } } }, "TemplateParameters": { "type": "array", "description": "The parameters are an array of strings, with the first string being used for `{{1}}` in the template, with the second being `{{2}}` etc. Only required if the template specified by `name` contains parameters.", "example": [ "Verification", "2526", "5" ], "items": { "type": "string" } }, "Image": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Image", "x-tab-id": "Image", "type": "object", "required": [ "image" ], "properties": { "message_type": { "type": "string", "enum": [ "image" ], "example": "image", "description": "The type of message to send. You must provide `image` in this field" }, "image": { "type": "object", "required": [ "url" ], "properties": { "url": { "format": "url", "description": "The publicly accessible URL of the image attachment. Supported types are .jpg, .jpeg, and .png", "example": "https://example.com/image.jpg", "type": "string" } } } } } ] }, "Audio": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Audio", "x-tab-id": "Audio", "type": "object", "required": [ "audio" ], "properties": { "message_type": { "type": "string", "enum": [ "audio" ], "example": "audio", "description": "The type of message to send. You must provide `audio` in this field" }, "audio": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "example": "https://example.com/audio.mp3" } } } } } ] }, "Video": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Video", "x-tab-id": "Video", "type": "object", "required": [ "video" ], "properties": { "message_type": { "type": "string", "enum": [ "video" ], "example": "video", "description": "The type of message to send. You must provide `video` in this field" }, "video": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Publicly accessible URL of the video attachment. Supports file types .mp4 and .3gpp > Note: Only supports video codec H.264 and audio codec AAC", "format": "url", "example": "https://example.com/video.mp4" } } } } } ] }, "vCard": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "vCard", "x-tab-id": "vCard", "type": "object", "required": [ "vcard" ], "properties": { "message_type": { "type": "string", "enum": [ "vcard" ], "example": "vcard", "description": "The type of message to send. You must provide `vcard` in this field" }, "vcard": { "type": "object", "required": [ "url" ], "properties": { "url": { "format": "url", "description": "The publicly accessible URL of the vCard attachment. Supported types are .vcf only", "example": "https://example.com/contact.vcf", "type": "string" } } } } } ] }, "Unsupported": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Unsupported", "x-tab-id": "Unsupported", "type": "object", "required": [ "message_type" ], "properties": { "message_type": { "type": "string", "enum": [ "unsupported" ], "example": "unsupported", "description": "The type of message to send. Will be `unsupported` if the type of message received from user is not supported by the channel." } } } ] }, "File": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "File", "x-tab-id": "File", "type": "object", "required": [ "file" ], "properties": { "message_type": { "type": "string", "enum": [ "file" ], "example": "file", "description": "The type of message to send. You must provide `file` in this field" }, "file": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "example": "https://example.com/file.pdf" } } } } } ] }, "Content": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Content", "x-tab-id": "Content", "type": "object", "required": [ "content" ], "properties": { "message_type": { "type": "string", "enum": [ "content" ], "example": "content", "description": "The type of message to send. You must provide `content` in this field" }, "content": { "type": "array", "description": "An array of one or more objects representing image, audio, video, vCard, or file attachments.", "items": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "description": "The type of attachment.", "example": "image", "enum": [ "image", "audio", "video", "vcard", "file" ] }, "url": { "type": "string", "description": "The URL of the attachment.", "example": "https://example.com/image.jpg" }, "caption": { "type": "string", "description": "Additional text to accompany the attachment.", "minLength": 1, "maxLength": 3000, "example": "See the attached image" } } } } } } ] }, "Template": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Template", "x-tab-id": "Template", "type": "object", "required": [ "template" ], "properties": { "message_type": { "type": "string", "enum": [ "template" ], "example": "template", "description": "The type of message to send. You must provide `template` in this field" }, "template": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "example": "verify", "description": "The name of the template to use." }, "parameters": { "$ref": "#/components/schemas/TemplateParameters" } } } } } ] }, "Custom": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Custom", "x-tab-id": "Custom", "type": "object", "required": [ "custom" ], "properties": { "message_type": { "type": "string", "enum": [ "custom" ], "example": "custom", "description": "The type of message to send. You must provide `custom` in this field" }, "custom": { "type": "object", "additionalProperties": true } } } ] }, "Reply": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Reply", "x-tab-id": "Reply", "type": "object", "required": [ "reply" ], "properties": { "message_type": { "type": "string", "enum": [ "reply" ], "example": "reply", "description": "The type of message. Must be `reply`." }, "reply": { "required": [ "id", "title" ], "type": "object", "properties": { "id": { "type": "string", "example": "reply_option_1", "description": "An identifier to help identify the selected reply." }, "title": { "type": "string", "example": "9am", "description": "The title text displayed on the selected reply." } } } } } ] }, "WhatsAppInboundButton": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Button (Flows)", "x-tab-id": "Button", "type": "object", "required": [ "button" ], "properties": { "message_type": { "type": "string", "enum": [ "button" ], "example": "button", "description": "The type of message. Must be `button`." }, "button": { "required": [ "payload" ], "type": "object", "properties": { "payload": { "type": "object", "example": { "flow_token": "", "optional_param1": "", "optional_param2": "" }, "description": "The payload for the button. Contents can be varied depending on the type of button." }, "text": { "type": "string", "example": "sent", "description": "Additional context for the button." }, "subtype": { "type": "string", "example": "flow", "description": "The sub type of button being received." } } } } } ] }, "WhatsAppInboundContact": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Contacts (beta)", "x-tab-id": "Contacts", "type": "object", "required": [ "button" ], "properties": { "message_type": { "type": "string", "enum": [ "contacts" ], "example": "contacts", "description": "The type of message. Must be `contacts`." }, "contacts": { "type": "array", "description": "An array of one or more contact objects.", "items": { "type": "object", "properties": { "addresses": { "type": "array", "description": "An array of one or more addresses for the contact.", "items": { "type": "object", "properties": { "city": { "type": "string", "example": "New York", "description": "The city of the contact." }, "country": { "type": "string", "example": "US", "description": "The country of the contact." }, "country_code": { "type": "string", "example": "1", "description": "The country code of the contact." }, "state": { "type": "string", "example": "NY", "description": "The state of the contact." }, "street": { "type": "string", "example": "123 Main St", "description": "The street of the contact." }, "type": { "type": "string", "example": "home", "description": "The type of address.", "enum": [ "home", "work" ] }, "postal_code": { "type": "string", "example": "10001", "description": "The postal/zip code of the contact." } } } }, "birthday": { "type": "string", "example": "1980-01-01", "description": "The birthday of the contact." }, "emails": { "type": "array", "description": "An array of one or more email addresses for the contact.", "items": { "type": "object", "properties": { "email": { "type": "string", "example": "bob@example.com", "description": "The email address of the contact." }, "type": { "type": "string", "example": "home", "description": "The type of email address.", "enum": [ "home", "work" ] } } } }, "name": { "type": "object", "description": "The name of the contact.", "properties": { "formatted_name": { "type": "string", "example": "Bob Smith", "description": "The full name of the contact." }, "first_name": { "type": "string", "example": "Bob", "description": "The first name of the contact." }, "last_name": { "type": "string", "example": "Smith", "description": "The last name of the contact." }, "middle_name": { "type": "string", "example": "John", "description": "The middle name of the contact." }, "prefix": { "type": "string", "example": "Mr", "description": "The prefix of the contact." }, "suffix": { "type": "string", "example": "Jr", "description": "The suffix of the contact." } } }, "phones": { "type": "array", "description": "An array of one or more phone numbers for the contact.", "items": { "type": "object", "properties": { "phone": { "type": "string", "example": "1234567890", "description": "The phone number of the contact." }, "type": { "type": "string", "example": "home", "description": "The type of phone number.", "enum": [ "home", "work" ] } } } }, "urls": { "type": "array", "description": "An array of one or more URLs for the contact.", "items": { "type": "object", "properties": { "url": { "type": "string", "example": "https://example.com", "description": "The URL of the contact." }, "type": { "type": "string", "example": "home", "description": "The type of URL.", "enum": [ "home", "work" ] } } } } } } } } } ] }, "Location": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Location", "x-tab-id": "Location", "type": "object", "required": [ "location" ], "properties": { "message_type": { "type": "string", "enum": [ "location" ], "example": "location", "description": "The type of message to send. You must provide `location` in this field" }, "location": { "required": [ "lat", "long" ], "type": "object", "properties": { "lat": { "type": "number", "example": 40.34772, "description": "Latitude of the location." }, "long": { "type": "number", "example": -74.18847, "description": "Longitude of the location." } } } } } ] }, "Button": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Button", "x-tab-id": "Button", "type": "object", "required": [ "reply" ], "properties": { "message_type": { "type": "string", "enum": [ "button" ], "example": "button", "description": "The type of message. Must be `button`." }, "button": { "required": [ "payload", "text" ], "type": "object", "properties": { "payload": { "type": "string", "example": "button_1", "description": "An identifier to help identify the selected button." }, "text": { "type": "string", "example": "Agree", "description": "The text displayed on the selected button." } } } } } ] }, "Order": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Order", "x-tab-id": "Order", "type": "object", "required": [ "order" ], "properties": { "message_type": { "type": "string", "enum": [ "order" ], "example": "order", "description": "The type of message to send." }, "order": { "required": [ "catalog_id", "product_items" ], "type": "object", "properties": { "catalog_id": { "type": "string", "example": "2806150799683508", "description": "The ID of the catalog containing the products in this order." }, "product_items": { "type": "array", "items": { "type": "object", "properties": { "product_retailer_id": { "type": "string", "example": "pk1v7rudbg", "description": "The ID of the specific product being ordered." }, "quantity": { "type": "string", "example": "1", "description": "The quantity ordered for this specific item." }, "item_price": { "type": "string", "example": "9.99", "description": "The unit price for this specific item." }, "currency": { "type": "string", "example": "USD", "description": "The currency code representing the currency for this specific item." } } } } } } } } ] }, "Sticker": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Sticker", "x-tab-id": "Sticker", "required": [ "sticker" ], "properties": { "message_type": { "type": "string", "enum": [ "sticker" ], "example": "sticker", "description": "The type of message to send. You must provide `sticker` in this field" }, "sticker": { "type": "object", "description": "Object with details of the sticker to send. Must contain either a URL or an ID, but not both. See the [documentation](/messages/guides/whatsapp-stickers) for more information on sending stickers.", "oneOf": [ { "$ref": "#/components/schemas/StickerWithURL" }, { "$ref": "#/components/schemas/StickerWithID" } ] } } } ] }, "StickerWithURL": { "description": "Sticker with URL", "type": "object", "required": [ "url" ], "properties": { "url": { "format": "url", "description": "The publicly accessible URL of the sticker image. Supported types are: .webp. See the [documentation](/messages/guides/whatsapp-stickers) for more information on sending stickers.", "example": "https://example.com/image.webp", "type": "string" } } }, "StickerWithID": { "description": "Sticker with ID (deprecated)", "type": "object", "required": [ "id" ], "properties": { "id": { "description": "The id of the sticker in relation to a specific WhatsApp deployment. See the [documentation](/messages/guides/whatsapp-stickers) for more information on sending stickers.", "example": "aabb7a31-1d1f-4755-a574-2971d831cd5b", "type": "string" } } }, "InboundSticker": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Sticker", "x-tab-id": "Sticker", "required": [ "sticker" ], "properties": { "message_type": { "type": "string", "enum": [ "sticker" ], "example": "sticker", "description": "The type of message." }, "sticker": { "type": "object", "description": "Object with a URL to access the sticker that was sent.", "required": [ "url" ], "properties": { "url": { "format": "url", "description": "The URL of the sticker image on Vonage's media servers.", "example": "https://api-us.nexmo.com/v3/media/1b456509-974c-458b-aafa-45fc48a4d976", "type": "string" } } } } } ] }, "OutboundReaction": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Reaction (beta)", "x-tab-id": "Reaction", "required": [ "reaction" ], "properties": { "message_type": { "type": "string", "enum": [ "reaction" ], "example": "reaction", "description": "The type of message to send. You must provide `reaction` in this field" }, "reaction": { "type": "object", "description": "Object with details of the reaction to send.", "required": [ "action" ], "oneOf": [ { "$ref": "#/components/schemas/ReactionReact" }, { "$ref": "#/components/schemas/ReactionUnreact" } ] } } } ] }, "InboundReaction": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Reaction (beta)", "x-tab-id": "Reaction", "required": [ "reaction" ], "properties": { "message_type": { "type": "string", "enum": [ "reaction" ], "example": "reaction", "description": "The type of message to received." }, "reaction": { "type": "object", "description": "Object with details of the reaction received.", "required": [ "action" ], "oneOf": [ { "$ref": "#/components/schemas/ReactionReact" }, { "$ref": "#/components/schemas/ReactionUnreact" } ] } } } ] }, "ReactionReact": { "description": "React", "type": "object", "required": [ "action", "emoji" ], "properties": { "action": { "type": "string", "example": "react", "description": "The action taken.", "enum": [ "react" ] }, "emoji": { "type": "string", "example": "😀", "description": "The emoji used as a reaction." } } }, "ReactionUnreact": { "description": "Unreact", "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "example": "unreact", "description": "The action taken.", "enum": [ "unreact" ] } } }, "Text": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Text", "x-tab-id": "Text", "description": "The text of message to send.", "required": [ "text" ], "properties": { "message_type": { "type": "string", "enum": [ "text" ], "example": "text", "description": "The type of message to send. You must provide `text` in this field" }, "text": { "type": "string", "example": "Hello from Vonage!" } } } ] }, "HTML": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "HTML", "x-tab-id": "HTML", "description": "The HTML content of the message to send.", "required": [ "html" ], "properties": { "message_type": { "type": "string", "enum": [ "html" ], "example": "html", "description": "The type of message to send. You must provide `html` in this field" } } } ] }, "EmailContent": { "allOf": [ { "$ref": "#/components/schemas/baseMessageType" }, { "title": "Content", "x-tab-id": "Content", "description": "The content of the email message to send, which can include text and/or HTML.", "required": [ "content" ], "properties": { "message_type": { "type": "string", "enum": [ "content" ], "example": "content", "description": "The type of message to send. You must provide `content` in this field" } } } ] }, "EmailContentText": { "title": "Text", "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ], "example": "text", "description": "The type for the content object. Must be `text`." }, "text": { "type": "string", "example": "Hello from Vonage!", "description": "The text content to display in the message." } } }, "EmailContentHtml": { "title": "HTML", "type": "object", "required": [ "type", "body" ], "properties": { "type": { "type": "string", "enum": [ "html" ], "example": "html", "description": "The type for the content object. Must be `html`." }, "body": { "type": "string", "example": "

Welcome to our service

We're glad to have you on board!

", "description": "The HTML content to display in the message." } } }, "ErrorChannel": { "description": "Unsupported channel", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/messages#1100" }, "title": { "type": "string", "description": "Generic error message", "example": "Unsupported channel" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The specified channel is not supported." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorChannelParams": { "description": "Invalid channel parameters", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/messages#1110" }, "title": { "type": "string", "description": "Generic error message", "example": "Invalid channel parameters" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The value of one or more parameters is invalid." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" }, "invalid_parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of invalid parameter", "example": "messenger.category" }, "reason": { "type": "string", "description": "Reason of failure", "example": "Must be one of `response`, `update` or `message_tag`." } } } } } }, "ErrorSender": { "description": "Invalid sender", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/messages#1120" }, "title": { "type": "string", "description": "Generic error message", "example": "Invalid sender" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The `from` parameter is invalid for the given channel." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorRecipient": { "description": "Invalid recipient", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/messages#110" }, "title": { "type": "string", "description": "Generic error message", "example": "Invalid recipient" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The `to` parameter is invalid for the given channel." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorMessageType": { "description": "Invalid message type", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/messages#1140" }, "title": { "type": "string", "description": "Generic error message", "example": "Invalid message type" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The `to` parameter is invalid for the given channel." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorMessageParams": { "description": "Invalid message parameters", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/messages#1150" }, "title": { "type": "string", "description": "Generic error message", "example": "Invalid params" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The value of one or more parameters is invalid." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" }, "invalid_parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of invalid parameter", "example": "image.url" }, "reason": { "type": "string", "description": "Reason of failure", "example": "is required." } } } } } }, "ErrorClientReference": { "description": "Invalid client reference", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/messages#1060" }, "title": { "type": "string", "description": "Generic error message", "example": "Invalid client reference" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "The client reference can be a string of up to 40 characters." }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "MessageUuid": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab", "description": "The UUID of the message" }, "WorkflowId": { "type": "string", "description": "The ID of the failover workflow. Only present if the request was sent with the `failover` property.", "example": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9" }, "ToNumber": { "type": "string", "minLength": 7, "maxLength": 15, "example": "447700900000", "description": "The phone number of the message **recipient** in the [E.164](https://en.wikipedia.org/wiki/E.164) format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000." }, "FromNumber": { "type": "string", "example": "447700900001", "description": "The phone number of the message **sender** in the [E.164](https://en.wikipedia.org/wiki/E.164) format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000. For SMS in certain localities alpha-numeric sender id's will work as well, see [Global Messaging](https://developer.vonage.com/messaging/sms/guides/country-specific-features#country-specific-features) for more details" }, "ToId": { "type": "string", "minLength": 1, "maxLength": 50, "example": "0123456789", "description": "The ID of the message recipient" }, "FromId": { "type": "string", "minLength": 1, "maxLength": 50, "example": "9876543210", "description": "The ID of the message sender" }, "RCSSenderId": { "type": "string", "description": "Specifies the Sender ID that will be displayed to the message recipient. This identifier should be alphanumeric and must match exactly the Sender ID registered during the onboarding process. Spaces are not permitted.", "example": "Vonage" }, "OutboundEmailTo": { "type": "string", "description": "The email address of the message recipient.", "example": "user@example.com" }, "OutboundEmailFrom": { "type": "string", "description": "The email address of the message sender. The domain will be need to be verified by Vonage prior to sending emails.\nSee the [documentation](https://developer.vonage.com//messages/concepts/getting-started/getting-started-email?source=messages#email-onboarding) for more information on setting up and verifying email domains.\n\nDisplay names can also be set in this field, using the following format: \"Display Name \\\".\n", "example": "no-reply@yourdomain.com" }, "InboundOrigin": { "type": "object", "properties": { "network_code": { "type": "string", "description": "The network code of the network from which the message originated (if available).", "example": "12345" } } }, "TrustedSender": { "type": "boolean", "description": "**DEPRECATED** This parameter is deprecated and will be removed in future. Please use `trusted_recipient` instead.", "example": true, "default": false, "deprecated": true }, "TrustedRecipient": { "type": "boolean", "description": "Setting this parameter to `true` overrides, on a per-message basis, any protections set up via [Fraud Defender](https://developer.vonage.com/en/fraud-defender/overview) (Traffic Rules, SMS Burst Protection, AIT Protection).\nThis parameter only has any effect for accounts subscribed to Fraud Defender Premium.", "example": true, "default": false }, "outboundMessageCommon": { "type": "object", "properties": { "client_ref": { "type": "string", "description": "Client reference of up to 100 characters. The reference will be present in every message status.", "example": "abc123" }, "webhook_url": { "type": "string", "description": "Specifies the URL to which Status Webhook messages will be sent *for this particular message*. Over-rides account-level and application-level Status Webhook url settings on a per-message basis.", "example": "https://example.com/status" }, "webhook_version": { "$ref": "#/components/schemas/WebhookVersion" } } }, "WebhookVersion": { "type": "string", "description": "Specifies which version of the Messages API will be used to send Status Webhook messages *for this particular message*. For example, if `v0.1` is set, then the JSON body of Status Webhook messages for this message will be sent in Messages v0.1 format. Over-rides account-level and application-level API version settings on a per-message basis.", "example": "v1", "enum": [ "v0.1", "v1" ] }, "baseMessageType": { "type": "object", "required": [ "to", "from", "message_type", "channel" ] }, "channelOptionsSms": { "type": "object", "properties": { "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "channel": { "type": "string", "description": "The channel to send to. You must provide `sms` in this field", "example": "sms", "enum": [ "sms" ] }, "ttl": { "type": "integer", "description": "The duration in seconds the delivery of an SMS will be attempted. By default Vonage attempts delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours. We recommend this value should be kept at its default or at least 30 minutes.", "example": 90000, "minimum": 20, "maximum": 604800 }, "trusted_sender": { "$ref": "#/components/schemas/TrustedSender" }, "trusted_recipient": { "$ref": "#/components/schemas/TrustedRecipient" }, "sms": { "type": "object", "description": "An object of optional settings for the SMS message.", "properties": { "encoding_type": { "type": "string", "description": "The encoding type to use for the message. If set to either `text` or `unicode` the specified type will be used. If set to `auto` (the default), the Messages API will automatically set the type based on the content of `text`; i.e. if unicode characters are detected in `text`, then the message will be encoded as unicode, and otherwise as text.", "example": "text", "enum": [ "text", "unicode", "auto" ] }, "content_id": { "description": "A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the [Country-Specific Outbound SMS Features](https://api.support.vonage.com/hc/en-us/sections/200622473-Country-Specific-Features-and-Restrictions)\"", "type": "string", "example": "1107457532145798767" }, "entity_id": { "description": "A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the [Country-Specific Outbound SMS Features](https://api.support.vonage.com/hc/en-us/sections/200622473-Country-Specific-Features-and-Restrictions)", "type": "string", "example": "1101456324675322134" }, "pool_id": { "description": "The ID of the Number Pool to use as the sender of this message. If specified, a number from the pool will be used as the `from` number. The `from` number is still required even when specifying a `pool_id` and will be used as a fall-back if the number pool cannot be used. See the [Number Pools documentation](https://developer.vonage.com/numbers/number-pools-api/overview) for more information.", "type": "string", "example": "abc123" } } } } }, "channelOptionsMms": { "type": "object", "properties": { "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "channel": { "type": "string", "description": "The channel to send to. You must provide `mms` in this field", "example": "mms", "enum": [ "mms" ] }, "mms": { "$ref": "#/components/schemas/mmsMessageObject" }, "ttl": { "minimum": 300, "maximum": 259200, "description": "Time-To-Live (how long a message should exist before it is delivered successfully) in seconds. If a message is not delivered successfully within the TTL time, the message is considered expired and will be rejected if TTL is supported.", "example": 600, "type": "integer" }, "trusted_sender": { "$ref": "#/components/schemas/TrustedSender" }, "trusted_recipient": { "$ref": "#/components/schemas/TrustedRecipient" } } }, "mmsMessageObject": { "type": "object", "description": "An object of optional settings for the MMS message.", "properties": { "participants": { "type": "array", "description": "An array of phone numbers in E.164 format representing the additional participants of the group MMS conversation.\n\nSee the [MMS Group Messaging documentation](https://developer.vonage.com/messages/concepts/mms/mms-group-messaging) for more information.\n", "items": { "type": "string", "example": "447700900002" } } } }, "channelOptionsRcsStandard": { "type": "object", "properties": { "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/RCSSenderId" }, "channel": { "type": "string", "description": "The channel to send to. You must provide `rcs` in this field", "example": "rcs", "enum": [ "rcs" ] }, "ttl": { "type": "integer", "minimum": 20, "maximum": 259200, "description": "The duration in seconds the delivery of a message will be attempted.", "example": 600 }, "trusted_sender": { "$ref": "#/components/schemas/TrustedSender" }, "trusted_recipient": { "$ref": "#/components/schemas/TrustedRecipient" }, "rcs": { "type": "object", "description": "An object of optional settings for the RCS message.", "properties": { "category": { "type": "string", "description": "A category describing the type of content contained in the RCS message. This is required when sending RCS messages in certain countries in order to comply with regional regulations and contractual agreements. If you are unsure about the restrictions and required categories for the country you are sending to, please see [this knowledgebase article](https://api.support.vonage.com/hc/en-us/articles/22562912482972-RCS-category-Field-France-Compliance-Rules) for further information, or contact your Vonage Account Manager.", "example": "transaction", "enum": [ "authentication", "transaction", "promotion", "service-request", "acknowledgement" ] } } } } }, "channelOptionsRcsRichCard": { "type": "object", "properties": { "rcs": { "type": "object", "description": "An object of optional settings for the RCS message.", "properties": { "card_orientation": { "type": "string", "description": "The orientation of the rich card.", "example": "VERTICAL", "enum": [ "VERTICAL", "HORIZONTAL" ] }, "image_alignment": { "type": "string", "description": "The alignment of the thumbnail image in the rich card.\nThis property only applies, and is **required**, when sending rich cards with a `card_orientation` of `HORIZONTAL`.", "example": "RIGHT", "enum": [ "RIGHT", "LEFT" ] } } } } }, "channelOptionsRcsCarousel": { "type": "object", "properties": { "rcs": { "type": "object", "description": "An object of optional settings for the RCS message.", "properties": { "card_width": { "type": "string", "description": "The width of the rich cards displayed in the carousel.", "example": "SMALL", "enum": [ "SMALL", "MEDIUM" ] } } } } }, "channelOptionsMessenger": { "type": "object", "properties": { "to": { "$ref": "#/components/schemas/ToId" }, "from": { "$ref": "#/components/schemas/FromId" }, "channel": { "description": "The channel to send to. You must provide `messenger` in this field", "type": "string", "example": "messenger", "enum": [ "messenger" ] }, "messenger": { "type": "object", "properties": { "category": { "type": "string", "example": "response", "description": "The use of different category tags enables the business to send messages for different use cases. For Facebook Messenger they need to comply with their [Messaging Types policy](https://developers.facebook.com/docs/messenger-platform/send-messages#messaging_types). Vonage maps our `category` to their `messaging_type`. If `message_tag` is used, then an additional `tag` for that type is mandatory. By default Vonage sends the `response` category to Facebook Messenger.", "enum": [ "response", "update", "message_tag" ] }, "tag": { "description": "A tag describing the type and relevance of the 1:1 communication between your app and the end user. A full list of available tags is available [here](https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags)", "example": "CONFIRMED_EVENT_UPDATE", "type": "string" } } } } }, "channelOptionsViber": { "type": "object", "properties": { "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/FromId" }, "channel": { "description": "The channel to send to. You must provide `viber_service` in this field", "type": "string", "example": "viber_service", "enum": [ "viber_service" ] }, "viber_service": { "type": "object", "properties": { "category": { "type": "string", "example": "transaction", "description": "The use of different category tags enables the business to send messages for different use cases. For Viber Business Messages the first message sent from a business to a user must be personal, informative & a targeted message - not promotional. By default Vonage sends the `transaction` category to Viber Business Messages.", "enum": [ "transaction", "promotion" ] }, "ttl": { "minimum": 30, "maximum": 259200, "description": "Set the time-to-live of message to be delivered in seconds. i.e. if the message is not delivered in 600 seconds then delete the message.", "example": 600, "type": "integer" }, "type": { "description": "Viber-specific type definition. For Belarus, Russia and Ukraine only, \"template\" can be used. Otherwise, the default \"string\" will be set. To use \"template\", please contact your Vonage Account Manager to setup your templates. To find out more please visit the [product page](https://www.vonage.com/communications-apis/messages/)", "type": "string", "example": "my-template" } } } } }, "channelOptionsViberVideo": { "type": "object", "required": [ "viber_service" ], "properties": { "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/FromId" }, "channel": { "description": "The channel to send to. You must provide `viber_service` in this field", "type": "string", "example": "viber_service", "enum": [ "viber_service" ] }, "viber_service": { "type": "object", "required": [ "duration", "file_size" ], "properties": { "category": { "type": "string", "example": "transaction", "description": "The use of different category tags enables the business to send messages for different use cases. For Viber Business Messages the first message sent from a business to a user must be personal, informative & a targeted message - not promotional. By default Vonage sends the `transaction` category to Viber Business Messages.", "enum": [ "transaction", "promotion" ] }, "duration": { "type": "string", "minimum": 1, "maximum": 600, "description": "The duration of the video in seconds.", "example": "123" }, "file_size": { "type": "string", "minimum": 1, "maximum": 200, "description": "The file size of the video in MB.", "example": "1" }, "ttl": { "minimum": 30, "maximum": 259200, "description": "Set the time-to-live of message to be delivered in seconds. i.e. if the message is not delivered in 600 seconds then delete the message.", "example": 600, "type": "integer" }, "type": { "description": "Viber-specific type definition. For Belarus, Russia and Ukraine only, \"template\" can be used. Otherwise, the default \"string\" will be set. To use \"template\", please contact your Vonage Account Manager to setup your templates. To find out more please visit the [product page](https://www.vonage.com/communications-apis/messages/)", "type": "string", "example": "my-template" } } } } }, "channelOptionsViberWithButton": { "type": "object", "properties": { "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/FromId" }, "channel": { "description": "The channel to send to. You must provide `viber_service` in this field", "type": "string", "example": "viber_service", "enum": [ "viber_service" ] }, "viber_service": { "type": "object", "properties": { "category": { "type": "string", "example": "transaction", "description": "The use of different category tags enables the business to send messages for different use cases. For Viber Business Messages the first message sent from a business to a user must be personal, informative & a targeted message - not promotional. By default Vonage sends the `transaction` category to Viber Business Messages.", "enum": [ "transaction", "promotion" ] }, "ttl": { "minimum": 30, "maximum": 259200, "description": "Set the time-to-live of message to be delivered in seconds. i.e. if the message is not delivered in 600 seconds then delete the message.", "example": 600, "type": "integer" }, "type": { "description": "Viber-specific type definition. For Belarus, Russia and Ukraine only, \"template\" can be used. Otherwise, the default \"string\" will be set. To use \"template\", please contact your Vonage Account Manager to setup your templates. To find out more please visit the [product page](https://www.vonage.com/communications-apis/messages/)", "type": "string", "example": "my-template" }, "action": { "description": "Node for Viber action buttons.", "type": "object", "required": [ "url", "text" ], "properties": { "url": { "description": "A URL which is requested when the action button is clicked.", "type": "string", "example": "https://example.com/page1.html" }, "text": { "description": "Text which is rendered on the action button.", "type": "string", "maxLength": 30, "example": "Find out more" } } } } } } }, "channelOptionsWhatsapp": { "type": "object", "properties": { "to": { "type": "string", "example": "447700900001", "description": "The phone number of the message **recipient** in the [E.164](https://en.wikipedia.org/wiki/E.164) format without a leading +, for example, 447700900000.\nA WhatsApp Business-scoped User ID (BSUID) can also be used in this field instead of a phone number, for example US.13491208655302741918.\nSee the [Meta documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids) for more information on BSUIDs.\n" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "channel": { "description": "The channel to send to. You must provide `whatsapp` in this field", "type": "string", "example": "whatsapp", "enum": [ "whatsapp" ] }, "context": { "description": "A context used for quoting/replying/reacting to a specific message in a conversation. When used for quoting or replying, the WhatsApp UI will display the new message along with a contextual bubble that displays the quoted/replied to message's content. When used for reacting the WhatsApp UI will display the reaction emoji below the reacted to message.", "type": "object", "required": [ "message_uuid" ], "properties": { "message_uuid": { "description": "The UUID of the message being quoted/replied/reacted to.", "type": "string", "example": "a1b2c3d4a1b2c3d4" } } } } }, "channelOptionsEmail": { "type": "object", "required": [ "email" ], "properties": { "to": { "$ref": "#/components/schemas/OutboundEmailTo" }, "from": { "$ref": "#/components/schemas/OutboundEmailFrom" }, "channel": { "type": "string", "description": "The channel to send to. You must provide `email` in this field", "example": "email", "enum": [ "email" ] }, "email": { "type": "object", "description": "An object of settings for the email message.", "required": [ "subject" ], "properties": { "subject": { "type": "string", "description": "The subject of the email. This will appear in the subject line of the email received by the end user.", "example": "Hello from Vonage" }, "importance": { "type": "string", "description": "The importance of the email message. This will be mapped to the `Importance` header in the email received by the end user, which may affect how the email is filtered and displayed by email clients.", "example": "High", "enum": [ "High", "Normal", "Low" ] }, "priority": { "type": "string", "description": "The priority of the email message. This will be mapped to the `Priority` header in the email received by the end user, which may affect how the email is filtered and displayed by email clients.", "example": "Non-urgent", "enum": [ "Non-urgent", "Normal", "Urgent" ] }, "sensitivity": { "type": "string", "description": "The sensitivity of the email message. This will be mapped to the `Sensitivity` header in the email received by the end user, which may affect how the email is filtered and displayed by email clients.", "example": "Personal", "enum": [ "Personal", "Private", "Company-Confidential" ] } } } } }, "messageStatusBase": { "type": "object", "properties": { "message_uuid": { "$ref": "#/components/schemas/MessageUuid" }, "timestamp": { "type": "string", "description": "The datetime of when the event occurred, in `ISO 8601` format.", "example": "2025-02-03T12:14:25Z" }, "status": { "type": "string", "description": "The status of the message.", "example": "submitted", "enum": [ "submitted", "delivered", "rejected", "undeliverable" ] }, "error": { "$ref": "#/components/schemas/messageStatusError" }, "client_ref": { "$ref": "#/components/schemas/messageStatusClientRef" }, "workflow": { "type": "object", "description": "An object containing details of the failover workflow that was used to send the message related to this status. Only present if the request was sent with the `failover` property.", "properties": { "workflow_id": { "description": "The ID of the failover workflow.", "allOf": [ { "$ref": "#/components/schemas/WorkflowId" } ] }, "items_number": { "type": "string", "description": "The position of the message related to this status within the failover workflow that was used to send the message. For example, an `items_number` of `1` indicates that this status relates to message that was the primary message in the request; an `items_number` of `2` indicates that this status relates to message that was the first message in the `failover` array, and so on.", "example": "1" }, "items_total": { "type": "string", "description": "The total number of messages in the request for the workflow related to this status, including the primary message and all messages in the `failover` array.", "example": "2" } } } }, "required": [ "message_uuid", "channel", "to", "from", "timestamp", "status" ] }, "messageStatusError": { "type": "object", "description": "If the message encountered a problem a descriptive error will be supplied in this object.", "properties": { "type": { "type": "string", "format": "url", "description": "The type of error encountered, follow URL for more details", "example": "https://developer.vonage.com/api-errors/messages#1000" }, "title": { "type": "string", "example": "1000", "description": "The error code encountered when sending the message. See [our errors list](/api-errors/messages) for a list of possible errors" }, "detail": { "type": "string", "example": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry", "description": "Text describing the error. See [our errors list](/api-errors/messages) for a list of possible errors" }, "instance": { "type": "string", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf", "description": "The record id of this error's occurrence." } } }, "messageStatusUsage": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "currency": { "type": "string", "example": "EUR", "description": "The charge currency in ISO 4217 format.", "enum": [ "EUR" ] }, "price": { "type": "string", "example": "0.0333", "description": "The charge amount as a stringified number." } } } } }, "messageStatusClientRef": { "type": "string", "description": "Client reference of up to 100 characters. Only present if this was set in the associated outbound message.", "example": "abc123" }, "messageStatusSMS": { "allOf": [ { "title": "SMS", "x-tab-id": "SMS", "description": "SMS", "properties": { "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "channel": { "type": "string", "description": "The channel for the message to which this status relates.", "example": "sms", "enum": [ "sms" ] }, "destination": { "$ref": "#/components/schemas/Destination" }, "sms": { "description": "Channel specific metadata for SMS", "type": "object", "properties": { "count_total": { "type": "string", "example": "2", "description": "The number of SMS messages concatenated together to comprise the submitted message. SMS messages are 160 characters, if a submitted message exceeds that size it is sent as multiple SMS messages. This number indicates how many SMS messages are required." } } } } }, { "$ref": "#/components/schemas/messageStatusBase" }, { "$ref": "#/components/schemas/messageStatusUsage" } ] }, "messageStatusMMS": { "allOf": [ { "title": "MMS", "x-tab-id": "MMS", "description": "MMS", "properties": { "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "channel": { "type": "string", "description": "The channel for the message to which this status relates.", "example": "mms", "enum": [ "mms" ] }, "destination": { "$ref": "#/components/schemas/Destination" } } }, { "$ref": "#/components/schemas/messageStatusBase" }, { "$ref": "#/components/schemas/messageStatusUsage" } ] }, "messageStatusRCS": { "allOf": [ { "title": "RCS", "x-tab-id": "RCS", "description": "RCS", "properties": { "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/RCSSenderId" }, "channel": { "type": "string", "description": "The channel for the message to which this status relates.", "example": "rcs", "enum": [ "rcs" ] }, "status": { "example": "read", "enum": [ "read" ] }, "destination": { "$ref": "#/components/schemas/Destination" } } }, { "$ref": "#/components/schemas/messageStatusBase" } ] }, "messageStatusWhatsApp": { "allOf": [ { "title": "WhatsApp", "x-tab-id": "WhatsApp", "description": "WhatsApp", "properties": { "to": { "type": "string", "example": "447700900001", "description": "The phone number of the message **recipient** in the [E.164](https://en.wikipedia.org/wiki/E.164) format without a leading +, for example, 447700900000.\nThis field might contain a WhatsApp Business-scoped User ID (BSUID) instead of a phone number in cases where the BSUID was used to send the message.\nSee the [Meta documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids) for more information on BSUIDs.\n" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "channel": { "type": "string", "description": "The channel for the message to which this status relates.", "example": "whatsapp", "enum": [ "whatsapp" ] }, "status": { "example": "read", "enum": [ "read" ] }, "usage": { "type": "object", "properties": { "currency": { "type": "string", "example": "EUR", "description": "The charge currency in ISO 4217 format.", "enum": [ "EUR" ] }, "price": { "type": "string", "example": "0", "description": "The charge amount as a stringified number. For WhatsApp this is the default Vonage charge per conversation for CBP, and will show as `0` for PMP. See [WhatsApp Pricing](/messages/concepts/whatsapp#whatsapp-message-based-pricing) for more details." } } }, "profile": { "$ref": "#/components/schemas/WhatsAppUserProfile" }, "whatsapp": { "type": "object", "description": "An object contining meta-data related to the WhatsApp message that triggered this callback. Only present for callbacks with a `status` of `delivered`.", "properties": { "recipient": { "$ref": "#/components/schemas/WhatsAppUserIdentity" }, "pricing": { "type": "object", "description": "An object containing pricing information for the WhatsApp message.", "properties": { "type": { "type": "string", "example": "regular", "description": "The pricing type for the message. See [WhatsApp Pricing](/messages/concepts/whatsapp#whatsapp-message-based-pricing) for more details.", "enum": [ "regular", "free_customer_service", "free_entry_point" ] }, "pricing_model": { "type": "string", "example": "CBP", "description": "Whether the message is priced at Per-Message Pricing (PMP) or Conversation-Based Pricing (CBP). See [WhatsApp Pricing](/messages/concepts/whatsapp#whatsapp-message-based-pricing) for more details.", "enum": [ "PMP", "CBP" ] }, "category": { "type": "string", "example": "service", "description": "The category of the WhatsApp message, which determines the pricing applied. See [WhatsApp Pricing](/messages/concepts/whatsapp#whatsapp-message-based-pricing) for more details.", "enum": [ "authentication", "authentication_international", "marketing", "utility", "service", "referral_conversion", "marketing_lite" ] } } }, "conversation": { "type": "object", "description": "An object contining data for the conversation to which the message relates.", "properties": { "id": { "type": "string", "example": "1234567890", "description": "The id of the conversation.\nEffective 1st July 2025, these are unique messages IDs generated by Meta instead of conversation IDs." }, "origin": { "type": "object", "description": "An object contining data related to the origin of the conversation.", "properties": { "type": { "type": "string", "example": "marketing", "description": "The conversation type.", "enum": [ "marketing", "utility", "authentication", "referral_conversion", "service" ] } } } } } } } } }, { "$ref": "#/components/schemas/messageStatusBase" } ] }, "messageStatusMessenger": { "allOf": [ { "title": "Messenger", "x-tab-id": "Messenger", "description": "Messenger", "properties": { "to": { "$ref": "#/components/schemas/ToId" }, "from": { "$ref": "#/components/schemas/FromId" }, "channel": { "type": "string", "description": "The channel for the message to which this status relates.", "example": "messenger", "enum": [ "messenger" ] }, "status": { "example": "read", "enum": [ "read" ] } } }, { "$ref": "#/components/schemas/messageStatusBase" }, { "$ref": "#/components/schemas/messageStatusUsage" } ] }, "messageStatusViber": { "allOf": [ { "title": "Viber", "x-tab-id": "Viber", "description": "Viber", "properties": { "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "channel": { "type": "string", "description": "The channel for the message to which this status relates.", "example": "viber_service", "enum": [ "viber_service" ] }, "status": { "example": "read", "enum": [ "read" ] } } }, { "$ref": "#/components/schemas/messageStatusBase" }, { "$ref": "#/components/schemas/messageStatusUsage" } ] }, "messageStatusEmail": { "allOf": [ { "title": "Email (beta)", "x-tab-id": "Email", "description": "Email", "properties": { "to": { "$ref": "#/components/schemas/OutboundEmailTo" }, "from": { "$ref": "#/components/schemas/OutboundEmailFrom" }, "channel": { "type": "string", "description": "The channel for the message to which this status relates.", "example": "email", "enum": [ "email" ] }, "status": { "enum": [ "read" ] } } }, { "$ref": "#/components/schemas/messageStatusBase" } ] }, "Timestamp": { "type": "string", "description": "The datetime of when the event occurred, in `ISO 8601` format.", "example": "2025-02-03T12:14:25Z" }, "Destination": { "type": "object", "properties": { "network_code": { "type": "string", "description": "Code indicating the terminating network for the number to which the message was sent. May not always be included in the message status data.", "example": "12345" } } }, "InboundViberMessageCommon": { "title": "Viber", "x-tab-id": "Viber", "required": [ "channel", "message_uuid", "to", "from", "timestamp" ], "properties": { "channel": { "type": "string", "description": "The channel that the message came in on", "enum": [ "viber_service" ], "example": "viber_service" }, "context": { "type": "object", "description": "Object containing contextual details for the inbound message when it is a response to another message.", "properties": { "message_uuid": { "type": "string", "description": "The ID of the message being replied to.", "example": "1234567890abcdef" } } }, "message_uuid": { "$ref": "#/components/schemas/MessageUuid" }, "to": { "$ref": "#/components/schemas/ToId" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "timestamp": { "$ref": "#/components/schemas/Timestamp" } } }, "InboundMessengerMessageCommon": { "title": "Messenger", "x-tab-id": "Messenger", "required": [ "channel", "message_uuid", "to", "from", "timestamp" ], "properties": { "channel": { "type": "string", "description": "The channel that the message came in on", "enum": [ "messenger" ], "example": "messenger" }, "message_uuid": { "$ref": "#/components/schemas/MessageUuid" }, "to": { "$ref": "#/components/schemas/ToId" }, "from": { "$ref": "#/components/schemas/FromId" }, "timestamp": { "$ref": "#/components/schemas/Timestamp" } } }, "inboundWhatsAppMessageCommon": { "title": "WhatsApp", "type": "object", "x-tab-id": "WhatsApp", "required": [ "channel", "message_uuid", "to", "from", "timestamp", "context_status" ], "properties": { "channel": { "type": "string", "description": "The channel that the message came in on", "enum": [ "whatsapp" ], "example": "whatsapp" }, "message_uuid": { "$ref": "#/components/schemas/MessageUuid" }, "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "type": "string", "example": "447700900001", "description": "The phone number of the message **sender** in the [E.164](https://en.wikipedia.org/wiki/E.164) format without a leading +, for example, 447700900000.\nThis field might contain a WhatsApp Business-scoped User ID (BSUID) instead of a phone number in cases where the sender has created a User Name in their WhatsApp profile.\nSee the [Meta documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids) for more information on BSUIDs.\n" }, "timestamp": { "$ref": "#/components/schemas/Timestamp" }, "profile": { "$ref": "#/components/schemas/WhatsAppUserProfile" }, "context_status": { "type": "string", "description": "Whether or not there is a context for this inbound message or not. If there is a context, and it is `available`, the context details will be contained in a `context` object. If there is a context, but it is `unavailable`, or if there is no context for message (`none`), then there will be no `context` object inluded in the body.", "enum": [ "none", "available", "unavailable" ], "example": "available" }, "context": { "$ref": "#/components/schemas/Context" }, "provider_message": { "type": "string", "description": "A message from the channel provider, which may contain a description, error codes or other information", "example": "Message delivered" } } }, "Self": { "properties": { "_self": { "type": "object", "description": "An object representing the inbound message containing a link to the message resource itself", "properties": { "href": { "type": "string", "description": "The URL for the message resource, including the geo-specific base URI", "example": "https://api-eu.vonage.com/v1/messages/aaaaaaa-bbbb-4ccc-8ddd-0123456789ab" } } } } }, "WhatsAppUserProfile": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name set for the profile associated with the WhatsApp user account for this message.", "example": "Jane Smith" }, "username": { "type": "string", "description": "The username set for the profile, if the user has created one, associated with the WhatsApp user account for this message.", "example": "janesmith123" } } }, "WhatsAppUserIdentity": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The Business-scoped User ID (BSUID) associated with the WhatsApp user's phone number for this message.\n\nSee the [Meta documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#business-scoped-user-id) for more details.\n", "example": "US.13491208655302741918" }, "parent_user_id": { "type": "string", "description": "The Parent Business-scoped User ID (BSUID) associated with the WhatsApp user account for this message.\n\nOnly present if the user has created a User Name in their WhatsApp profile, and the business has enrolled their business portfolios to receive parent BSUIDs.\nSee the [Meta documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#parent-business-scoped-user-ids) for more details.\n", "example": "US.ENT.11815799212886844830" }, "wa_id": { "type": "string", "description": "The WhatsApp ID for the user, which is the phone number associated with the WhatsApp account in E.164 format.", "example": "447700900000" } } }, "WhatsAppSender": { "type": "object", "properties": { "sender": { "$ref": "#/components/schemas/WhatsAppUserIdentity" } } }, "Context": { "type": "object", "description": "This is only present for the Inbound Message where the user is quoting or reacting to another message. It provides information about the quoted message and/or the product message being responded to.", "required": [ "message_uuid", "message_from" ], "properties": { "message_uuid": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab", "description": "The UUID of the message being quoted." }, "message_from": { "type": "string", "example": "447700900000", "description": "The phone number of the **original sender** of the message being quoted in the [E.164](https://en.wikipedia.org/wiki/E.164) format." } } }, "WhatsAppReferralInfo": { "properties": { "referral": { "type": "object", "description": "This is only present for situations where a user has clicked on a 'WhatsApp' button embedded in an advertisement or post on Facebook. Clicking on the button directs the user to the WhatsApp app from where they can send a message. The inbound message will contain this object which includes details of the Facebook advertisement or post which contained the embedded button.", "required": [ "body", "headline", "source_id", "source_type", "source_url" ], "properties": { "body": { "type": "string", "example": "Check out our new product offering", "description": "Body text of the referring advertisement or post." }, "headline": { "type": "string", "example": "New Products!", "description": "Headline text of the referring advertisement or post." }, "source_id": { "type": "string", "example": "212731241638144", "description": "Meta/WhatsApp ID of the referring advertisement or post." }, "source_type": { "type": "string", "example": "post", "description": "The type of the referring advertisement or post." }, "source_url": { "type": "string", "example": "https://fb.me/2ZulEu42P", "description": "A URL referencing the content of the media shown in the advertisement when the user clicked to send a message." }, "media_type": { "type": "string", "example": "image", "description": "The type of media shown in the advertisement or post.", "enum": [ "image", "video" ] }, "image_url": { "type": "string", "example": "https://example.com/image.jpg", "description": "URL of the image shown in the advertisement or post." }, "video_url": { "type": "string", "example": "https://example.com/video.mp4", "description": "URL of the video shown in the advertisement or post." }, "thumbnail_url": { "type": "string", "example": "https://example.com/thumbnail.jpg", "description": "URL of the thumbnail image shown in the advertisement or post." }, "ctwa_clid": { "type": "string", "example": "1234567890", "description": "The click ID of the advertisement or post." } } } } }, "WhatsAppOrderInfo": { "properties": { "whatsapp_referred_product": { "type": "object", "description": "An object containing details of a product from a `product` message being quoted or replied to using the 'Message Business' option.", "required": [ "catalog_id", "product_retailer_id" ], "properties": { "catalog_id": { "type": "string", "example": "1267260820787549", "description": "The ID of the catalog associated with the product from the `product` message being quoted or replied to using the 'Message Business' option." }, "product_retailer_id": { "type": "string", "example": "r07qei73l7", "description": "The ID of the product from the `product` message being quoted or replied to using the 'Message Business' option." } } } } }, "Usage": { "type": "object", "properties": { "currency": { "type": "string", "example": "EUR", "description": "The charge currency in ISO 4217 format.", "enum": [ "EUR" ] }, "price": { "type": "string", "example": "0.0333", "description": "The charge amount as a stringified number." } } }, "inboundMessageSMS": { "title": "SMS", "type": "object", "required": [ "channel", "message_uuid", "to", "from", "timestamp", "text" ], "properties": { "channel": { "type": "string", "enum": [ "sms" ], "description": "The channel the message came in on", "example": "sms" }, "message_uuid": { "$ref": "#/components/schemas/MessageUuid" }, "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "timestamp": { "$ref": "#/components/schemas/Timestamp" }, "text": { "example": "Hello From Vonage!", "type": "string", "description": "The UTF-8 encoded text of the inbound message." }, "sms": { "description": "Channel specific metadata for SMS", "type": "object", "properties": { "num_messages": { "type": "string", "example": "2", "description": "The number of inbound SMS messages concatenated together to comprise this message. SMS messages are 160 characters, if an inbound message exceeds that size they are concatenated together to form a single message. This number indicates how many messages formed this webhook." }, "keyword": { "type": "string", "example": "HELLO", "description": "The first word of the message sent to uppercase." } } }, "usage": { "$ref": "#/components/schemas/Usage" }, "origin": { "$ref": "#/components/schemas/InboundOrigin" } } }, "inboundMessageMMS": { "title": "MMS", "x-tab-id": "MMS", "type": "object", "required": [ "channel", "message_uuid", "to", "from", "timestamp" ], "properties": { "channel": { "type": "string", "enum": [ "mms" ], "description": "The channel the message came in on", "example": "mms" }, "message_uuid": { "$ref": "#/components/schemas/MessageUuid" }, "to": { "$ref": "#/components/schemas/ToNumber" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "timestamp": { "$ref": "#/components/schemas/Timestamp" }, "origin": { "$ref": "#/components/schemas/InboundOrigin" }, "mms": { "$ref": "#/components/schemas/mmsMessageObject" } } }, "inboundMessageRCS": { "title": "RCS", "x-tab-id": "RCS", "type": "object", "required": [ "channel", "message_uuid", "to", "from", "timestamp" ], "properties": { "channel": { "type": "string", "enum": [ "rcs" ], "description": "The channel the message came in on", "example": "rcs" }, "message_uuid": { "$ref": "#/components/schemas/MessageUuid" }, "to": { "type": "string", "description": "Specifies the RCS Sender ID from which was received the outbound message to which this inbound message is replying.", "example": "Vonage" }, "from": { "$ref": "#/components/schemas/FromNumber" }, "timestamp": { "$ref": "#/components/schemas/Timestamp" }, "context_status": { "type": "string", "description": "Whether or not there is a context for this inbound message or not. RCS messages currently don't support context, so this will always be `none`.", "enum": [ "none" ], "example": "none" } } }, "multifileContent": { "properties": { "content": { "type": "array", "description": "An array of one or more objects representing image, audio, video, vCard, or file attachments. Only present for messages that have more than one attachment.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of attachment.", "example": "image", "enum": [ "image", "audio", "video", "vcard", "file" ] }, "url": { "type": "string", "description": "The URL of the attachment.", "example": "https://example.com/image.jpg" } } } } } }, "ErrorResponse": { "type": "object", "description": "Base error response following RFC 7807", "required": [ "type", "title", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors" }, "title": { "type": "string", "description": "Generic error message", "example": "An error occurred" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "More details about what went wrong" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "ErrorInvalidJson": { "description": "Invalid JSON", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors#invalid-json" }, "title": { "type": "string", "description": "Generic error message", "example": "The request body did not contain valid JSON" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } } }, "headers": { "X-Request-Id": { "description": "A unique identifier for the request, used for tracking and debugging", "schema": { "type": "string", "format": "uuid", "example": "f94b4e56-604e-07e5-e5ad-5a7228618f81" } }, "X-RateLimit-Limit": { "description": "Request limit per hour", "schema": { "type": "integer", "example": 30 } }, "X-RateLimit-Remaining": { "description": "Remaining requests", "schema": { "type": "integer", "example": 5 } }, "X-RateLimit-Reset": { "description": "Unix timestamp when limit resets", "schema": { "type": "integer", "example": 1769182705723 } }, "Retry-After": { "description": "Seconds until next request allowed", "schema": { "type": "integer", "example": 15 } } } }, "x-errors": { "1000": { "description": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry" }, "1010": { "description": "Missing params - Your request is incomplete and missing some mandatory parameters." }, "1020": { "description": "Invalid params - The value of one or more parameters is invalid." }, "1021": { "description": "Invalid tag - The tag value is invalid." }, "1022": { "description": "Invalid template - Invalid template or template parameters" }, "1030": { "description": "Internal error - There was an error processing your request in the Platform." }, "1040": { "description": "Invalid message - The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number." }, "1050": { "description": "Number barred - The number you are trying to submit to is blacklisted and may not receive messages." }, "1060": { "description": "Partner account barred - The `api_key` you supplied is for an account that has been barred from submitting messages." }, "1070": { "description": "Provider quota exceeded - your allocated quota may have been exceeded." }, "1080": { "description": "Account not enabled for REST - This account is not provisioned for REST submission, you should use SMPP on the SMS API." }, "1090": { "description": "Message too long - The length of `udh` and `body` was greater than 140 octets for a binary type SMS request." }, "1100": { "description": "Communication Failed - Message was not submitted because there was a communication failure." }, "1120": { "description": "Illegal Sender Address - rejected - Due to local regulations, the `SenderID` you set in from in the request was not accepted. Please check the Global messaging section." }, "1130": { "description": "Invalid TTL - The value of `ttl` in your request was invalid." }, "1140": { "description": "Facility not allowed - Your request makes use of a facility that is not enabled on your account." }, "1150": { "description": "Invalid Message class - The value of `message-`class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme." }, "1160": { "description": "Non White-listed Destination - The phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard." }, "1170": { "description": "Invalid recipient - The `to` parameter is missing or contains an invalid address or identifier." }, "1180": { "description": "Destination temporarily unavailable - The destination cannot currently receive messages. Retry later." }, "1190": { "description": "Absent Subscriber Permanent - `to` is no longer active, You should remove this phone number from your database." }, "1200": { "description": "Portability Error - There is an issue after the user has changed carrier for to. If the user wants to receive messages from you, they need to contact their carrier directly." }, "1210": { "description": "Anti-Spam Rejection - Carriers often apply restrictions that block messages following different criteria. For example on SenderID or message content." }, "1220": { "description": "Handset Busy - The handset associated with to was not available when this message was sent. If status is rejected, this is a temporary failure; retry later for a positive result. If status is submitted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours." }, "1230": { "description": "Temporary network failure - The message could not be delivered due to a network issue. Retry later." }, "1240": { "description": "Illegal Number - You tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you." }, "1241": { "description": "Too many send requests - Too many send requests to phone numbers." }, "1242": { "description": "Number pool does not exists - check that the number pool has been configured for your account" }, "1250": { "description": "Unroutable - The chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message." }, "1251": { "description": "Unable to route traffic to a destination - This may be due to the routing rules applied for your destination network." }, "1260": { "description": "Destination unreachable - The message could not be delivered to the phone number. If using Viber Business Messages your account might not be enabled for this country." }, "1270": { "description": "Subscriber Age Restriction - The carrier blocked this message because the content is not suitable for to based on age restrictions." }, "1280": { "description": "Number Blocked by Carrier - The carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended." }, "1282": { "description": "Message rejected by provider - The provider blocked the message may be due to policy or content restrictions." }, "1290": { "description": "Pre-Paid - Insufficient funds - to's pre-paid account does not have enough credit to receive the message." }, "1300": { "description": "Not part of the provider network - The number or ID is not a user in the provider network." }, "1310": { "description": "Not suitable device - The user's device can't receive the message." }, "1320": { "description": "Message already sent - The message was already sent." }, "1330": { "description": "Delivery failed - The provider returned an unknown permanent failure. Verify the destination and retry if appropriate." }, "1331": { "description": "Provider error - The provider is not responding or unable to process the request. Please try sending your message in a few minutes time." }, "1340": { "description": "Outside of the allowed window - This message is sent outside of allowed response window." }, "1350": { "description": "Phone matching fee not paid - Requires phone matching access fee to be paid by the Facebook Page." }, "1360": { "description": "TTL was activated, or message expired before delivered." }, "1370": { "description": "Expired access Token - Please reauthenticate your Facebook Page with Vonage." }, "1380": { "description": "Invalid resource - Please check that the URL your provided to your resource is accessible and valid." }, "1381": { "description": "Resource size is too large - Please try sending a smaller media file." }, "1382": { "description": "Unsupported resource type - The attached resource type is not supported or invalid." }, "1400": { "description": "Unsupported channel - The channel specified in the request is not supported." }, "1410": { "description": "Invalid channel parameters - The value of one or more parameters is invalid." }, "1420": { "description": "Invalid sender - The `from` parameter is invalid for the given channel." }, "1430": { "description": "Invalid recipient - The `to` parameter is invalid for the given channel." }, "1431": { "description": "Multiple recipients error - Multiple recipients not supported." }, "1440": { "description": "Invalid message type - The message type specified in the request is not supported for the given channel." }, "1450": { "description": "Invalid client reference - The client reference can be a string of up to 100 characters." }, "1451": { "description": "Invalid context - the reference to the original message could not be found because it is invalid or no longer available." }, "1460": { "description": "Daily message limit exceeded - Check compliance with regulations such as 10DLC." }, "1461": { "description": "Auto-limiting of messages by Provider - This message was not delivered by Provider to avoid excessive messages to the end user. For details please see this [knowledgebase article](https://api.support.vonage.com/hc/en-us/articles/17270698783516-WhatsApp-Per-User-Marketing-Template-Messaging-Limits)." }, "1470": { "description": "Fraud Defender Traffic Rule - Rejected due to Fraud Defender traffic rules block." }, "1472": { "description": "Fraud Defender SMS Burst Protection - Traffic limit has been reached" }, "1473": { "description": "AIT Protection - The message has been rejected by Fraud Defender AIT Protection" }, "1474": { "description": "Fraud Defender Traffic Rule - Rejected due to Fraud Defender country block." }, "1475": { "description": "Fraud Defender Traffic Rule - Rejected due to Fraud Defender network block." }, "1476": { "description": "Do Not Originate (DNO) - Originating number is on a DNO list." }, "1480": { "description": "Entity Filter - The message failed due to `entity_id` being incorrect or not provided. [More information on country specific regulations](https://api.support.vonage.com/hc/en-us/sections/200622473-Country-Specific-Features-and-Restrictions)." }, "1481": { "description": "Header Filter - The message failed because the header ID (`from` phone number) was incorrect or missing. [More information on country specific regulations](https://api.support.vonage.com/hc/en-us/sections/200622473-Country-Specific-Features-and-Restrictions)." }, "1482": { "description": "Content Filter - The message failed due to `content_id` being incorrect or not provided. [More information on country specific regulations](https://api.support.vonage.com/hc/en-us/sections/200622473-Country-Specific-Features-and-Restrictions)." }, "1483": { "description": "Consent Filter - The message failed due to consent not being authorized. [More information on country specific regulations](https://api.support.vonage.com/hc/en-us/sections/200622473-Country-Specific-Features-and-Restrictions)." }, "1484": { "description": "Authentication or compliance failure - The message failed authentication or regulatory checks. Verify sender configuration or contact [support](mailto:${CUSTOMER_SUPPORT_EMAIL})." }, "2001": { "description": "Fraud protection triggered - The message was blocked by fraud or abuse protection rules at the provider side." }, "2002": { "description": "Email size exceeded - The message or payload exceeds the allowed size limit. Reduce the payload and retry." }, "2003": { "description": "Destination unavailable - Recipient email address is in the suppression list, which may be due to an earlier email being hard bounced or marked as spam by the user." } } }