{ "swagger": "2.0", "info": { "title": "CommunicationMessagesClient", "version": "2024-08-30", "description": "Azure Communication Messages Service", "x-typespec-generated": [ { "emitter": "@azure-tools/typespec-autorest" } ] }, "schemes": [ "https" ], "x-ms-parameterized-host": { "hostTemplate": "{endpoint}", "useSchemePrefix": false, "parameters": [ { "name": "endpoint", "in": "path", "description": "The communication resource, for example https://my-resource.communication.azure.com", "required": true, "type": "string", "format": "uri", "x-ms-skip-url-encoding": true } ] }, "produces": [ "application/json" ], "consumes": [ "application/json" ], "security": [ { "AadOauth2Auth": [ "https://communication.azure.com/.default" ] }, { "ApiKeyAuth": [] } ], "securityDefinitions": { "AadOauth2Auth": { "type": "oauth2", "description": "The Azure Active Directory OAuth2 Flow", "flow": "accessCode", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "scopes": { "https://communication.azure.com/.default": "" }, "tokenUrl": "https://login.microsoftonline.com/common/oauth2/token" }, "ApiKeyAuth": { "type": "apiKey", "name": "Authorization", "in": "header" } }, "tags": [ { "name": "Template" }, { "name": "Notifications" }, { "name": "Stream" } ], "paths": { "/messages/channels/{channelId}/templates": { "get": { "operationId": "TemplateOperations_ListTemplates", "tags": [ "Template" ], "description": "List all templates for given Azure Communication Services channel", "parameters": [ { "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" }, { "name": "channelId", "in": "path", "description": "The registration ID of the channel.", "required": true, "type": "string", "format": "uuid" }, { "name": "maxpagesize", "in": "query", "description": "Number of objects to return per page.", "required": false, "type": "integer", "format": "int32" }, { "$ref": "#/parameters/Azure.Core.ClientRequestIdHeader" } ], "responses": { "200": { "description": "The request has succeeded.", "schema": { "$ref": "#/definitions/PagedMessageTemplateItem" }, "headers": { "x-ms-client-request-id": { "type": "string", "format": "uuid", "description": "An opaque, globally-unique, client-generated string identifier for the request." } } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Azure.Core.Foundations.ErrorResponse" }, "headers": { "x-ms-error-code": { "type": "string", "description": "String error code indicating what went wrong." } } } }, "x-ms-examples": { "Gets a list of templates": { "$ref": "./examples/Template_ListTemplates.json" } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/messages/notifications:send": { "post": { "operationId": "NotificationMessagesOperations_Send", "tags": [ "Notifications" ], "description": "Sends a notification message from Business to User.", "parameters": [ { "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" }, { "$ref": "#/parameters/Azure.Core.RepeatabilityRequestHeaders.repeatabilityRequestId" }, { "$ref": "#/parameters/Azure.Core.RepeatabilityRequestHeaders.repeatabilityFirstSent" }, { "$ref": "#/parameters/Azure.Core.ClientRequestIdHeader" }, { "$ref": "#/parameters/NotificationMessagesSendRequestBody" } ], "responses": { "202": { "description": "The request has been accepted for processing, but processing has not yet completed.", "schema": { "$ref": "#/definitions/SendMessageResult" }, "headers": { "Repeatability-Result": { "type": "string", "description": "Indicates whether the repeatable request was accepted or rejected.", "enum": [ "accepted", "rejected" ], "x-ms-enum": { "name": "RepeatabilityResult", "modelAsString": false, "values": [ { "name": "accepted", "value": "accepted", "description": "If the request was accepted and the server guarantees that the server state reflects a single execution of the operation." }, { "name": "rejected", "value": "rejected", "description": "If the request was rejected because the combination of Repeatability-First-Sent and Repeatability-Request-ID were invalid\nor because the Repeatability-First-Sent value was outside the range of values held by the server." } ] } }, "x-ms-client-request-id": { "type": "string", "format": "uuid", "description": "An opaque, globally-unique, client-generated string identifier for the request." } } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Azure.Core.Foundations.ErrorResponse" }, "headers": { "x-ms-error-code": { "type": "string", "description": "String error code indicating what went wrong." } } } }, "x-ms-examples": { "Sends a notification message - Template": { "$ref": "./examples/NotificationMessages_SendTemplate.json" }, "Sends a notification message - audio": { "$ref": "./examples/NotificationMessages_SendAudio.json" }, "Sends a notification message - document": { "$ref": "./examples/NotificationMessages_SendDocument.json" }, "Sends a notification message - image": { "$ref": "./examples/NotificationMessages_SendImage.json" }, "Sends a notification message - text": { "$ref": "./examples/NotificationMessages_SendText.json" }, "Sends a notification message - video": { "$ref": "./examples/NotificationMessages_SendVideo.json" } } } }, "/messages/streams/{id}": { "get": { "operationId": "StreamOperations_GetMedia", "tags": [ "Stream" ], "description": "Download the Media payload from a User to Business message.", "produces": [ "application/octet-stream", "application/json" ], "parameters": [ { "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" }, { "name": "id", "in": "path", "description": "The stream ID.", "required": true, "type": "string" }, { "$ref": "#/parameters/Azure.Core.ClientRequestIdHeader" } ], "responses": { "200": { "description": "The request has succeeded.", "schema": { "type": "file" }, "headers": { "x-ms-client-request-id": { "type": "string", "format": "uuid", "description": "An opaque, globally-unique, client-generated string identifier for the request." } } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Azure.Core.Foundations.ErrorResponse" }, "headers": { "x-ms-error-code": { "type": "string", "description": "String error code indicating what went wrong." } } } }, "x-ms-examples": { "Download media": { "$ref": "./examples/Stream_GetMedia.json" } } } } }, "definitions": { "AudioNotificationContent": { "type": "object", "description": "A request to send an audio notification.", "properties": { "mediaUri": { "type": "string", "format": "uri", "description": "A media url for the file. Required if the type is one of the supported media types, e.g. image" } }, "required": [ "mediaUri" ], "allOf": [ { "$ref": "#/definitions/NotificationContent" } ], "x-ms-discriminator-value": "audio" }, "Azure.Core.Foundations.Error": { "type": "object", "description": "The error object.", "properties": { "code": { "type": "string", "description": "One of a server-defined set of error codes." }, "message": { "type": "string", "description": "A human-readable representation of the error." }, "target": { "type": "string", "description": "The target of the error." }, "details": { "type": "array", "description": "An array of details about specific errors that led to this reported error.", "items": { "$ref": "#/definitions/Azure.Core.Foundations.Error" } }, "innererror": { "$ref": "#/definitions/Azure.Core.Foundations.InnerError", "description": "An object containing more specific information than the current object about the error." } }, "required": [ "code", "message" ] }, "Azure.Core.Foundations.ErrorResponse": { "type": "object", "description": "A response containing error details.", "properties": { "error": { "$ref": "#/definitions/Azure.Core.Foundations.Error", "description": "The error object." } }, "required": [ "error" ] }, "Azure.Core.Foundations.InnerError": { "type": "object", "description": "An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.", "properties": { "code": { "type": "string", "description": "One of a server-defined set of error codes." }, "innererror": { "$ref": "#/definitions/Azure.Core.Foundations.InnerError", "description": "Inner error." } } }, "Azure.Core.uuid": { "type": "string", "format": "uuid", "description": "Universally Unique Identifier" }, "CommunicationMessageKind": { "type": "string", "description": "The type of message.", "enum": [ "text", "image", "image_v0", "document", "video", "audio", "template" ], "x-ms-enum": { "name": "CommunicationMessageKind", "modelAsString": true, "values": [ { "name": "text", "value": "text", "description": "Text message type." }, { "name": "image", "value": "image", "description": "Image message type." }, { "name": "image_v0", "value": "image_v0", "description": "Image message type. Legacy image type for `MediaNotificationContent` which is being deprecated" }, { "name": "document", "value": "document", "description": "Document message type." }, { "name": "video", "value": "video", "description": "Video message type." }, { "name": "audio", "value": "audio", "description": "Audio message type." }, { "name": "template", "value": "template", "description": "Template message type." } ] } }, "CommunicationMessagesChannel": { "type": "string", "description": "The type of the communication messages channel.", "enum": [ "whatsApp" ], "x-ms-enum": { "name": "CommunicationMessagesChannel", "modelAsString": true, "values": [ { "name": "whatsApp", "value": "whatsApp", "description": "The WhatsApp communication messages channel type." } ] } }, "DocumentNotificationContent": { "type": "object", "description": "A request to send a document notification.", "properties": { "caption": { "type": "string", "description": "Optional text content." }, "fileName": { "type": "string", "description": "Optional name for the file." }, "mediaUri": { "type": "string", "format": "uri", "description": "A media url for the file. Required if the type is one of the supported media types, e.g. image" } }, "required": [ "mediaUri" ], "allOf": [ { "$ref": "#/definitions/NotificationContent" } ], "x-ms-discriminator-value": "document" }, "ImageNotificationContent": { "type": "object", "description": "A request to send an image notification.", "properties": { "caption": { "type": "string", "description": "Optional text content." }, "mediaUri": { "type": "string", "format": "uri", "description": "A media url for the file. Required if the type is one of the supported media types, e.g. image" } }, "required": [ "mediaUri" ], "allOf": [ { "$ref": "#/definitions/NotificationContent" } ], "x-ms-discriminator-value": "image" }, "MediaNotificationContent": { "type": "object", "description": "@deprecated A request to send an image notification.", "properties": { "content": { "type": "string", "description": "Optional text content." }, "mediaUri": { "type": "string", "format": "uri", "description": "A media url for the file. Required if the type is one of the supported media types, e.g. image" } }, "required": [ "mediaUri" ], "allOf": [ { "$ref": "#/definitions/NotificationContent" } ], "x-ms-discriminator-value": "image_v0" }, "MessageReceipt": { "type": "object", "description": "Receipt of the sending one message.", "properties": { "messageId": { "type": "string", "description": "The message id." }, "to": { "type": "string", "description": "The native external platform user identifier of the recipient." } }, "required": [ "messageId", "to" ] }, "MessageTemplate": { "type": "object", "description": "The template object used to create templates.", "properties": { "name": { "type": "string", "description": "Name of the template." }, "language": { "type": "string", "description": "The template's language, in the ISO 639 format, consist of a two-letter language code followed by an optional two-letter country code, e.g., 'en' or 'en_US'." }, "values": { "type": "array", "description": "The template values.", "items": { "$ref": "#/definitions/MessageTemplateValue" } }, "bindings": { "$ref": "#/definitions/MessageTemplateBindings", "description": "The binding object to link values to the template specific locations" } }, "required": [ "name", "language" ] }, "MessageTemplateBindings": { "type": "object", "description": "The binding object to link values to the template specific locations", "properties": { "kind": { "$ref": "#/definitions/MessageTemplateBindingsKind", "description": "The type discriminator describing a template bindings type." } }, "discriminator": "kind", "required": [ "kind" ] }, "MessageTemplateBindingsKind": { "type": "string", "description": "The type of the message template.", "enum": [ "whatsApp" ], "x-ms-enum": { "name": "MessageTemplateBindingsKind", "modelAsString": true, "values": [ { "name": "whatsApp", "value": "whatsApp", "description": "The WhatsApp template type." } ] } }, "MessageTemplateDocument": { "type": "object", "description": "The message template's document value information.", "properties": { "url": { "type": "string", "format": "uri", "description": "The (public) URL of the media." }, "caption": { "type": "string", "description": "The [optional] caption of the media object." }, "fileName": { "type": "string", "description": "The [optional] filename of the media file." } }, "required": [ "url" ], "allOf": [ { "$ref": "#/definitions/MessageTemplateValue" } ], "x-ms-discriminator-value": "document" }, "MessageTemplateImage": { "type": "object", "description": "The message template's image value information.", "properties": { "url": { "type": "string", "format": "uri", "description": "The (public) URL of the media." }, "caption": { "type": "string", "description": "The [optional] caption of the media object." }, "fileName": { "type": "string", "description": "The [optional] filename of the media file." } }, "required": [ "url" ], "allOf": [ { "$ref": "#/definitions/MessageTemplateValue" } ], "x-ms-discriminator-value": "image" }, "MessageTemplateItem": { "type": "object", "description": "The message template as returned from the service.", "properties": { "name": { "type": "string", "description": "The template's name.", "readOnly": true }, "language": { "type": "string", "description": "The template's language, in the ISO 639 format, consist of a two-letter language code followed by an optional two-letter country code, e.g., 'en' or 'en_US'." }, "status": { "$ref": "#/definitions/MessageTemplateStatus", "description": "The aggregated template status." }, "kind": { "$ref": "#/definitions/CommunicationMessagesChannel", "description": "The type discriminator describing a template type." } }, "discriminator": "kind", "required": [ "name", "language", "status", "kind" ] }, "MessageTemplateLocation": { "type": "object", "description": "The message template's location value information.", "properties": { "locationName": { "type": "string", "description": "The [Optional] name of the location." }, "address": { "type": "string", "description": "The [Optional] address of the location." }, "latitude": { "type": "number", "format": "double", "description": "The latitude of the location." }, "longitude": { "type": "number", "format": "double", "description": "The longitude of the location." } }, "required": [ "latitude", "longitude" ], "allOf": [ { "$ref": "#/definitions/MessageTemplateValue" } ], "x-ms-discriminator-value": "location" }, "MessageTemplateQuickAction": { "type": "object", "description": "The message template's quick action value information.", "properties": { "text": { "type": "string", "description": "The [Optional] quick action text" }, "payload": { "type": "string", "description": "The [Optional] quick action payload" } }, "allOf": [ { "$ref": "#/definitions/MessageTemplateValue" } ], "x-ms-discriminator-value": "quickAction" }, "MessageTemplateStatus": { "type": "string", "description": "The aggregated template status.", "enum": [ "approved", "rejected", "pending", "paused" ], "x-ms-enum": { "name": "MessageTemplateStatus", "modelAsString": true, "values": [ { "name": "approved", "value": "approved", "description": "Message template is approved." }, { "name": "rejected", "value": "rejected", "description": "Message template is rejected." }, { "name": "pending", "value": "pending", "description": "Message template is pending." }, { "name": "paused", "value": "paused", "description": "Message template is paused." } ] } }, "MessageTemplateText": { "type": "object", "description": "The message template's text value information.", "properties": { "text": { "type": "string", "description": "The text value." } }, "required": [ "text" ], "allOf": [ { "$ref": "#/definitions/MessageTemplateValue" } ], "x-ms-discriminator-value": "text" }, "MessageTemplateValue": { "type": "object", "description": "The class describes a parameter of a template.", "properties": { "name": { "type": "string", "description": "Template binding reference name" }, "kind": { "$ref": "#/definitions/MessageTemplateValueKind", "description": "The type discriminator describing a template parameter type." } }, "discriminator": "kind", "required": [ "name", "kind" ] }, "MessageTemplateValueKind": { "type": "string", "description": "The type of the template parameter.", "enum": [ "text", "image", "document", "video", "location", "quickAction" ], "x-ms-enum": { "name": "MessageTemplateValueKind", "modelAsString": true, "values": [ { "name": "text", "value": "text", "description": "The text template parameter type." }, { "name": "image", "value": "image", "description": "The image template parameter type." }, { "name": "document", "value": "document", "description": "The document template parameter type." }, { "name": "video", "value": "video", "description": "The video template parameter type." }, { "name": "location", "value": "location", "description": "The location template parameter type." }, { "name": "quickAction", "value": "quickAction", "description": "The quick action template parameter type." } ] } }, "MessageTemplateVideo": { "type": "object", "description": "The message template's video value information.", "properties": { "url": { "type": "string", "format": "uri", "description": "The (public) URL of the media." }, "caption": { "type": "string", "description": "The [optional] caption of the media object." }, "fileName": { "type": "string", "description": "The [optional] filename of the media file." } }, "required": [ "url" ], "allOf": [ { "$ref": "#/definitions/MessageTemplateValue" } ], "x-ms-discriminator-value": "video" }, "NotificationContent": { "type": "object", "description": "Details of the message to send.", "properties": { "channelRegistrationId": { "$ref": "#/definitions/Azure.Core.uuid", "description": "The Channel Registration ID for the Business Identifier." }, "to": { "type": "array", "description": "The native external platform user identifiers of the recipient.", "items": { "type": "string" } }, "kind": { "$ref": "#/definitions/CommunicationMessageKind", "description": "The type discriminator describing a message type." } }, "discriminator": "kind", "required": [ "channelRegistrationId", "to", "kind" ] }, "PagedMessageTemplateItem": { "type": "object", "description": "Paged collection of MessageTemplateItem items", "properties": { "value": { "type": "array", "description": "The MessageTemplateItem items on this page", "items": { "$ref": "#/definitions/MessageTemplateItem" } }, "nextLink": { "type": "string", "format": "uri", "description": "The link to the next page of items" } }, "required": [ "value" ] }, "SendMessageResult": { "type": "object", "description": "Result of the send message operation.", "properties": { "receipts": { "type": "array", "description": "Receipts of the send message operation.", "items": { "$ref": "#/definitions/MessageReceipt" } } }, "required": [ "receipts" ] }, "TemplateNotificationContent": { "type": "object", "description": "A request to send a template notification.", "properties": { "template": { "$ref": "#/definitions/MessageTemplate", "description": "The template object used to create templates." } }, "required": [ "template" ], "allOf": [ { "$ref": "#/definitions/NotificationContent" } ], "x-ms-discriminator-value": "template" }, "TextNotificationContent": { "type": "object", "description": "A request to send a text notification.", "properties": { "content": { "type": "string", "description": "Message content." } }, "required": [ "content" ], "allOf": [ { "$ref": "#/definitions/NotificationContent" } ], "x-ms-discriminator-value": "text" }, "VideoNotificationContent": { "type": "object", "description": "A request to send a video notification.", "properties": { "caption": { "type": "string", "description": "Optional text content." }, "mediaUri": { "type": "string", "format": "uri", "description": "A media url for the file. Required if the type is one of the supported media types, e.g. image" } }, "required": [ "mediaUri" ], "allOf": [ { "$ref": "#/definitions/NotificationContent" } ], "x-ms-discriminator-value": "video" }, "WhatsAppMessageButtonSubType": { "type": "string", "description": "The WhatsApp button sub type.", "enum": [ "quickReply", "url" ], "x-ms-enum": { "name": "WhatsAppMessageButtonSubType", "modelAsString": true, "values": [ { "name": "quickReply", "value": "quickReply", "description": "The WhatsApp button sub type is quick reply." }, { "name": "url", "value": "url", "description": "The WhatsApp button sub type is url." } ] } }, "WhatsAppMessageTemplateBindings": { "type": "object", "description": "The template bindings for WhatsApp", "properties": { "header": { "type": "array", "description": "The header template bindings", "items": { "$ref": "#/definitions/WhatsAppMessageTemplateBindingsComponent" } }, "body": { "type": "array", "description": "The body template bindings", "items": { "$ref": "#/definitions/WhatsAppMessageTemplateBindingsComponent" } }, "footer": { "type": "array", "description": "The footer template bindings", "items": { "$ref": "#/definitions/WhatsAppMessageTemplateBindingsComponent" } }, "buttons": { "type": "array", "description": "The button template bindings", "items": { "$ref": "#/definitions/WhatsAppMessageTemplateBindingsButton" } } }, "allOf": [ { "$ref": "#/definitions/MessageTemplateBindings" } ], "x-ms-discriminator-value": "whatsApp" }, "WhatsAppMessageTemplateBindingsButton": { "type": "object", "description": "The template bindings component button for WhatsApp", "properties": { "subType": { "$ref": "#/definitions/WhatsAppMessageButtonSubType", "description": "The WhatsApp button sub type" }, "refValue": { "type": "string", "description": "The name of the referenced item in the template values." } }, "required": [ "subType", "refValue" ] }, "WhatsAppMessageTemplateBindingsComponent": { "type": "object", "description": "The template bindings component for WhatsApp", "properties": { "refValue": { "type": "string", "description": "The name of the referenced item in the template values." } }, "required": [ "refValue" ] }, "WhatsAppMessageTemplateItem": { "type": "object", "description": "The WhatsApp-specific template response contract", "properties": { "content": { "description": "WhatsApp platform's template content. This is the payload returned from WhatsApp API." } }, "allOf": [ { "$ref": "#/definitions/MessageTemplateItem" } ], "x-ms-discriminator-value": "whatsApp" } }, "parameters": { "Azure.Core.ClientRequestIdHeader": { "name": "x-ms-client-request-id", "in": "header", "description": "An opaque, globally-unique, client-generated string identifier for the request.", "required": false, "type": "string", "format": "uuid", "x-ms-parameter-location": "method", "x-ms-client-name": "clientRequestId" }, "Azure.Core.Foundations.ApiVersionParameter": { "name": "api-version", "in": "query", "description": "The API version to use for this operation.", "required": true, "type": "string", "minLength": 1, "x-ms-parameter-location": "method", "x-ms-client-name": "apiVersion" }, "Azure.Core.RepeatabilityRequestHeaders.repeatabilityFirstSent": { "name": "Repeatability-First-Sent", "in": "header", "description": "Specifies the date and time at which the request was first created.", "required": false, "type": "string", "format": "date-time", "x-ms-parameter-location": "method", "x-ms-client-name": "repeatabilityFirstSent" }, "Azure.Core.RepeatabilityRequestHeaders.repeatabilityRequestId": { "name": "Repeatability-Request-ID", "in": "header", "description": "An opaque, globally-unique, client-generated string identifier for the request.", "required": false, "type": "string", "x-ms-parameter-location": "method", "x-ms-client-name": "repeatabilityRequestId" }, "NotificationMessagesSendRequestBody": { "name": "body", "in": "body", "description": "Details of the message to send.", "required": true, "schema": { "$ref": "#/definitions/NotificationContent" }, "x-ms-parameter-location": "method" } } }