Notification Messages Operations - Send

Service:: Communication

API Version:: 2024-08-30

Sends a notification message from Business to User.

POST {endpoint}/messages/notifications:send?api-version=2024-08-30

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string (uri)	The communication resource, for example https://my-resource.communication.azure.com
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Header

Name	Type	Description
Repeatability-Request-ID	string	An opaque, globally-unique, client-generated string identifier for the request.
Repeatability-First-Sent	string (date-time)	Specifies the date and time at which the request was first created.
x-ms-client-request-id	string (uuid)	An opaque, globally-unique, client-generated string identifier for the request.

Request Body

The request body can be one of the following:

Name	Description
AudioNotificationContent	A request to send an audio notification.
DocumentNotificationContent	A request to send a document notification.
ImageNotificationContent	A request to send an image notification.
MediaNotificationContent	@deprecated A request to send an image notification.
TemplateNotificationContent	A request to send a template notification.
TextNotificationContent	A request to send a text notification.
VideoNotificationContent	A request to send a video notification.

AudioNotificationContent

A request to send an audio notification.

Name	Required	Type	Description
channelRegistrationId	True	string (uuid)	The Channel Registration ID for the Business Identifier.
kind	True	string: audio	The type discriminator describing a message type.
mediaUri	True	string (uri)	A media url for the file. Required if the type is one of the supported media types, e.g. image
to	True	string[]	The native external platform user identifiers of the recipient.

DocumentNotificationContent

A request to send a document notification.

Name	Required	Type	Description
channelRegistrationId	True	string (uuid)	The Channel Registration ID for the Business Identifier.
kind	True	string: document	The type discriminator describing a message type.
mediaUri	True	string (uri)	A media url for the file. Required if the type is one of the supported media types, e.g. image
to	True	string[]	The native external platform user identifiers of the recipient.
caption		string	Optional text content.
fileName		string	Optional name for the file.

ImageNotificationContent

A request to send an image notification.

Name	Required	Type	Description
channelRegistrationId	True	string (uuid)	The Channel Registration ID for the Business Identifier.
kind	True	string: image	The type discriminator describing a message type.
mediaUri	True	string (uri)	A media url for the file. Required if the type is one of the supported media types, e.g. image
to	True	string[]	The native external platform user identifiers of the recipient.
caption		string	Optional text content.

MediaNotificationContent

@deprecated A request to send an image notification.

Name	Required	Type	Description
channelRegistrationId	True	string (uuid)	The Channel Registration ID for the Business Identifier.
kind	True	string: image_v0	The type discriminator describing a message type.
mediaUri	True	string (uri)	A media url for the file. Required if the type is one of the supported media types, e.g. image
to	True	string[]	The native external platform user identifiers of the recipient.
content		string	Optional text content.

TemplateNotificationContent

A request to send a template notification.

Name	Required	Type	Description
channelRegistrationId	True	string (uuid)	The Channel Registration ID for the Business Identifier.
kind	True	string: template	The type discriminator describing a message type.
template	True	MessageTemplate	The template object used to create templates.
to	True	string[]	The native external platform user identifiers of the recipient.

TextNotificationContent

A request to send a text notification.

Name	Required	Type	Description
channelRegistrationId	True	string (uuid)	The Channel Registration ID for the Business Identifier.
content	True	string	Message content.
kind	True	string: text	The type discriminator describing a message type.
to	True	string[]	The native external platform user identifiers of the recipient.

VideoNotificationContent

A request to send a video notification.

Name	Required	Type	Description
channelRegistrationId	True	string (uuid)	The Channel Registration ID for the Business Identifier.
kind	True	string: video	The type discriminator describing a message type.
mediaUri	True	string (uri)	A media url for the file. Required if the type is one of the supported media types, e.g. image
to	True	string[]	The native external platform user identifiers of the recipient.
caption		string	Optional text content.

Responses

Name	Type	Description
202 Accepted	SendMessageResult	The request has been accepted for processing, but processing has not yet completed. Headers Repeatability-Result: string x-ms-client-request-id: string
Other Status Codes	Azure.Core.Foundations.ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

202 Accepted

SendMessageResult

The request has been accepted for processing, but processing has not yet completed.

Headers

Repeatability-Result: string
x-ms-client-request-id: string

Other Status Codes

Azure.Core.Foundations.ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

AadOauth2Auth

The Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: accessCode
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize
Token URL: https://login.microsoftonline.com/common/oauth2/token

Scopes

Name	Description
https://communication.azure.com/.default

Authorization

Type: apiKey
In: header

Examples

Sends a notification message - audio

Sends a notification message - document

Sends a notification message - image

Sends a notification message - Template

Sends a notification message - text

Sends a notification message - video

Sends a notification message - audio

Sample request

HTTP

POST https://my-resource.communication.azure.com/messages/notifications:send?api-version=2024-08-30

{
  "channelRegistrationId": "0f0eb78e-a576-1dfc-b414-0f0756de3338",
  "to": [
    "14250000000"
  ],
  "kind": "audio",
  "mediaUri": "https://example.com/audio.mp3"
}

Sample response

Status code:: 202

{
  "receipts": [
    {
      "messageId": "320fc2a1-4c4b-4387-9c1a-bd38b57795de",
      "to": "14250000000"
    }
  ]
}

Sends a notification message - document

Sample request

HTTP

POST https://my-resource.communication.azure.com/messages/notifications:send?api-version=2024-08-30

{
  "channelRegistrationId": "0f0eb78e-a576-1dfc-b414-0f0756de3338",
  "to": [
    "14250000000"
  ],
  "kind": "document",
  "mediaUri": "https://example.com/document.pdf",
  "caption": "check out this document!",
  "fileName": "fileName.pdf"
}

Sample response

Status code:: 202

{
  "receipts": [
    {
      "messageId": "320fc2a1-4c4b-4387-9c1a-bd38b57795de",
      "to": "14250000000"
    }
  ]
}

Sends a notification message - image

Sample request

HTTP

POST https://my-resource.communication.azure.com/messages/notifications:send?api-version=2024-08-30

{
  "channelRegistrationId": "0f0eb78e-a576-1dfc-b414-0f0756de3338",
  "to": [
    "14250000000"
  ],
  "kind": "image",
  "mediaUri": "https://example.com/image.jpg",
  "caption": "check out this image!"
}

Sample response

Status code:: 202

{
  "receipts": [
    {
      "messageId": "320fc2a1-4c4b-4387-9c1a-bd38b57795de",
      "to": "14250000000"
    }
  ]
}

Sends a notification message - Template

Sample request

HTTP

POST https://my-resource.communication.azure.com/messages/notifications:send?api-version=2024-08-30

{
  "channelRegistrationId": "0f0eb78e-a576-1dfc-b414-0f0756de3338",
  "to": [
    "14250000000"
  ],
  "kind": "template",
  "template": {
    "name": "example",
    "language": "en",
    "values": [
      {
        "name": "userName",
        "kind": "text",
        "text": "John Doe"
      },
      {
        "name": "orderNumber",
        "kind": "text",
        "text": "12345"
      }
    ],
    "bindings": {
      "body": [
        {
          "refValue": "userName"
        },
        {
          "refValue": "orderNumber"
        }
      ],
      "kind": "whatsApp"
    }
  }
}

Sample response

Status code:: 202

{
  "receipts": [
    {
      "messageId": "320fc2a1-4c4b-4387-9c1a-bd38b57795de",
      "to": "14250000000"
    }
  ]
}

Sends a notification message - text

Sample request

HTTP

POST https://my-resource.communication.azure.com/messages/notifications:send?api-version=2024-08-30

{
  "channelRegistrationId": "0f0eb78e-a576-1dfc-b414-0f0756de3338",
  "to": [
    "14250000000"
  ],
  "kind": "text",
  "content": "Text message through CPM"
}

Sample response

Status code:: 202

{
  "receipts": [
    {
      "messageId": "320fc2a1-4c4b-4387-9c1a-bd38b57795de",
      "to": "14250000000"
    }
  ]
}

Sends a notification message - video

Sample request

HTTP

POST https://my-resource.communication.azure.com/messages/notifications:send?api-version=2024-08-30

{
  "channelRegistrationId": "0f0eb78e-a576-1dfc-b414-0f0756de3338",
  "to": [
    "14250000000"
  ],
  "kind": "video",
  "mediaUri": "https://example.com/video.mp4",
  "caption": "check out this video!"
}

Sample response

Status code:: 202

{
  "receipts": [
    {
      "messageId": "320fc2a1-4c4b-4387-9c1a-bd38b57795de",
      "to": "14250000000"
    }
  ]
}

Definitions

Name	Description
AudioNotificationContent	A request to send an audio notification.
Azure.Core.Foundations.Error	The error object.
Azure.Core.Foundations.ErrorResponse	A response containing error details.
Azure.Core.Foundations.InnerError	An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.
CommunicationMessageKind	The type of message.
DocumentNotificationContent	A request to send a document notification.
ImageNotificationContent	A request to send an image notification.
MediaNotificationContent	@deprecated A request to send an image notification.
MessageReceipt	Receipt of the sending one message.
MessageTemplate	The template object used to create templates.
MessageTemplateBindingsKind	The type of the message template.
MessageTemplateDocument	The message template's document value information.
MessageTemplateImage	The message template's image value information.
MessageTemplateLocation	The message template's location value information.
MessageTemplateQuickAction	The message template's quick action value information.
MessageTemplateText	The message template's text value information.
MessageTemplateValueKind	The type of the template parameter.
MessageTemplateVideo	The message template's video value information.
SendMessageResult	Result of the send message operation.
TemplateNotificationContent	A request to send a template notification.
TextNotificationContent	A request to send a text notification.
VideoNotificationContent	A request to send a video notification.
WhatsAppMessageButtonSubType	The WhatsApp button sub type.
WhatsAppMessageTemplateBindings	The template bindings for WhatsApp
WhatsAppMessageTemplateBindingsButton	The template bindings component button for WhatsApp
WhatsAppMessageTemplateBindingsComponent	The template bindings component for WhatsApp

AudioNotificationContent

Object

A request to send an audio notification.

Name	Type	Description
channelRegistrationId	string (uuid)	The Channel Registration ID for the Business Identifier.
kind	string: audio	The type discriminator describing a message type.
mediaUri	string (uri)	A media url for the file. Required if the type is one of the supported media types, e.g. image
to	string[]	The native external platform user identifiers of the recipient.

Azure.Core.Foundations.Error

Object

The error object.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	Azure.Core.Foundations.Error[]	An array of details about specific errors that led to this reported error.
innererror	Azure.Core.Foundations.InnerError	An object containing more specific information than the current object about the error.
message	string	A human-readable representation of the error.
target	string	The target of the error.

Azure.Core.Foundations.ErrorResponse

Object

A response containing error details.

Name	Type	Description
error	Azure.Core.Foundations.Error	The error object.

Azure.Core.Foundations.InnerError

Object

An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.

Name	Type	Description
code	string	One of a server-defined set of error codes.
innererror	Azure.Core.Foundations.InnerError	Inner error.

CommunicationMessageKind

Enumeration

The type of message.

Value	Description
text	Text message type.
image	Image message type.
image_v0	Image message type. Legacy image type for `MediaNotificationContent` which is being deprecated
document	Document message type.
video	Video message type.
audio	Audio message type.
template	Template message type.

DocumentNotificationContent

Object

A request to send a document notification.

Name	Type	Description
caption	string	Optional text content.
channelRegistrationId	string (uuid)	The Channel Registration ID for the Business Identifier.
fileName	string	Optional name for the file.
kind	string: document	The type discriminator describing a message type.
mediaUri	string (uri)	A media url for the file. Required if the type is one of the supported media types, e.g. image
to	string[]	The native external platform user identifiers of the recipient.

ImageNotificationContent

Object

A request to send an image notification.

Name	Type	Description
caption	string	Optional text content.
channelRegistrationId	string (uuid)	The Channel Registration ID for the Business Identifier.
kind	string: image	The type discriminator describing a message type.
mediaUri	string (uri)	A media url for the file. Required if the type is one of the supported media types, e.g. image
to	string[]	The native external platform user identifiers of the recipient.

MediaNotificationContent

Object

@deprecated A request to send an image notification.

Name	Type	Description
channelRegistrationId	string (uuid)	The Channel Registration ID for the Business Identifier.
content	string	Optional text content.
kind	string: image_v0	The type discriminator describing a message type.
mediaUri	string (uri)	A media url for the file. Required if the type is one of the supported media types, e.g. image
to	string[]	The native external platform user identifiers of the recipient.

MessageReceipt

Object

Receipt of the sending one message.

Name	Type	Description
messageId	string	The message id.
to	string	The native external platform user identifier of the recipient.

MessageTemplate

Object

The template object used to create templates.

Name	Type	Description
bindings	MessageTemplateBindings: WhatsAppMessageTemplateBindings	The binding object to link values to the template specific locations
language	string	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'.
name	string	Name of the template.
values	MessageTemplateValue[]: MessageTemplateDocument[] MessageTemplateImage[] MessageTemplateLocation[] MessageTemplateQuickAction[] MessageTemplateText[] MessageTemplateVideo[]	The template values.

MessageTemplateBindingsKind

Enumeration

The type of the message template.

Value	Description
whatsApp	The WhatsApp template type.

MessageTemplateDocument

Object

The message template's document value information.

Name	Type	Description
caption	string	The [optional] caption of the media object.
fileName	string	The [optional] filename of the media file.
kind	string: document	The type discriminator describing a template parameter type.
name	string	Template binding reference name
url	string (uri)	The (public) URL of the media.

MessageTemplateImage

Object

The message template's image value information.

Name	Type	Description
caption	string	The [optional] caption of the media object.
fileName	string	The [optional] filename of the media file.
kind	string: image	The type discriminator describing a template parameter type.
name	string	Template binding reference name
url	string (uri)	The (public) URL of the media.

MessageTemplateLocation

Object

The message template's location value information.

Name	Type	Description
address	string	The [Optional] address of the location.
kind	string: location	The type discriminator describing a template parameter type.
latitude	number (double)	The latitude of the location.
locationName	string	The [Optional] name of the location.
longitude	number (double)	The longitude of the location.
name	string	Template binding reference name

MessageTemplateQuickAction

Object

The message template's quick action value information.

Name	Type	Description
kind	string: quickAction	The type discriminator describing a template parameter type.
name	string	Template binding reference name
payload	string	The [Optional] quick action payload
text	string	The [Optional] quick action text

MessageTemplateText

Object

The message template's text value information.

Name	Type	Description
kind	string: text	The type discriminator describing a template parameter type.
name	string	Template binding reference name
text	string	The text value.

MessageTemplateValueKind

Enumeration

The type of the template parameter.

Value	Description
text	The text template parameter type.
image	The image template parameter type.
document	The document template parameter type.
video	The video template parameter type.
location	The location template parameter type.
quickAction	The quick action template parameter type.

MessageTemplateVideo

Object

The message template's video value information.

Name	Type	Description
caption	string	The [optional] caption of the media object.
fileName	string	The [optional] filename of the media file.
kind	string: video	The type discriminator describing a template parameter type.
name	string	Template binding reference name
url	string (uri)	The (public) URL of the media.

SendMessageResult

Object

Result of the send message operation.

Name	Type	Description
receipts	MessageReceipt[]	Receipts of the send message operation.

TemplateNotificationContent

Object

A request to send a template notification.

Name	Type	Description
channelRegistrationId	string (uuid)	The Channel Registration ID for the Business Identifier.
kind	string: template	The type discriminator describing a message type.
template	MessageTemplate	The template object used to create templates.
to	string[]	The native external platform user identifiers of the recipient.

TextNotificationContent

Object

A request to send a text notification.

Name	Type	Description
channelRegistrationId	string (uuid)	The Channel Registration ID for the Business Identifier.
content	string	Message content.
kind	string: text	The type discriminator describing a message type.
to	string[]	The native external platform user identifiers of the recipient.

VideoNotificationContent

Object

A request to send a video notification.

Name	Type	Description
caption	string	Optional text content.
channelRegistrationId	string (uuid)	The Channel Registration ID for the Business Identifier.
kind	string: video	The type discriminator describing a message type.
mediaUri	string (uri)	A media url for the file. Required if the type is one of the supported media types, e.g. image
to	string[]	The native external platform user identifiers of the recipient.

WhatsAppMessageButtonSubType

Enumeration

The WhatsApp button sub type.

Value	Description
quickReply	The WhatsApp button sub type is quick reply.
url	The WhatsApp button sub type is url.

WhatsAppMessageTemplateBindings

Object

The template bindings for WhatsApp

Name	Type	Description
body	WhatsAppMessageTemplateBindingsComponent[]	The body template bindings
buttons	WhatsAppMessageTemplateBindingsButton[]	The button template bindings
footer	WhatsAppMessageTemplateBindingsComponent[]	The footer template bindings
header	WhatsAppMessageTemplateBindingsComponent[]	The header template bindings
kind	string: whatsApp	The type discriminator describing a template bindings type.

WhatsAppMessageTemplateBindingsButton

Object

The template bindings component button for WhatsApp

Name	Type	Description
refValue	string	The name of the referenced item in the template values.
subType	WhatsAppMessageButtonSubType	The WhatsApp button sub type

WhatsAppMessageTemplateBindingsComponent

Object

The template bindings component for WhatsApp

Name	Type	Description
refValue	string	The name of the referenced item in the template values.

Share via

Notification Messages Operations - Send

URI Parameters

Request Header

Request Body

AudioNotificationContent

DocumentNotificationContent

ImageNotificationContent

MediaNotificationContent

TemplateNotificationContent

TextNotificationContent

VideoNotificationContent

Responses

Security

AadOauth2Auth

Scopes

Authorization

Examples

Sends a notification message - audio

Sample request

Sample response

Sends a notification message - document

Sample request

Sample response

Sends a notification message - image

Sample request

Sample response

Sends a notification message - Template

Sample request

Sample response

Sends a notification message - text

Sample request

Sample response

Sends a notification message - video

Sample request

Sample response

Definitions

AudioNotificationContent

Azure.Core.Foundations.Error

Azure.Core.Foundations.ErrorResponse

Azure.Core.Foundations.InnerError

CommunicationMessageKind

DocumentNotificationContent

ImageNotificationContent

MediaNotificationContent

MessageReceipt

MessageTemplate

MessageTemplateBindingsKind

MessageTemplateDocument

MessageTemplateImage

MessageTemplateLocation

MessageTemplateQuickAction

MessageTemplateText

MessageTemplateValueKind

MessageTemplateVideo

SendMessageResult

TemplateNotificationContent

TextNotificationContent

VideoNotificationContent

WhatsAppMessageButtonSubType

WhatsAppMessageTemplateBindings

WhatsAppMessageTemplateBindingsButton

WhatsAppMessageTemplateBindingsComponent