Share via

Notification Messages Operations - Send

  • Reference
Service:
Communication
API Version:
2024-02-01

Sends a notification message from Business to User.

POST {endpoint}/messages/notifications:send?api-version=2024-02-01

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

The API version to use for this operation.

Request Header

Name Required 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
MediaNotificationContent

A request to send an image notification.
TemplateNotificationContent

A request to send a template notification.
TextNotificationContent

A request to send a text notification.

MediaNotificationContent

A request to send an image notification.

Name Required Type Description
channelRegistrationId True

string

The Channel Registration ID for the Business Identifier.
kind True string:

image

The type discriminator describing a notification type.
mediaUri True

string

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

The Channel Registration ID for the Business Identifier.
kind True string:

template

The type discriminator describing a notification 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

The Channel Registration ID for the Business Identifier.
content True

string

Message content.
kind True string:

text

The type discriminator describing a notification type.
to True

string[]

The native external platform user identifiers of the recipient.

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

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 - image
Sends a notification message - Template
Sends a notification message - text

Sends a notification message - image

Sample request

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

{
  "channelRegistrationId": "0f0eb78e-a576-1dfc-b414-0f0756de3338",
  "to": [
    "14250000000"
  ],
  "kind": "image",
  "mediaUri": "https://example.com/image.jpg",
  "content": "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

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

{
  "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

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

{
  "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"
    }
  ]
}

Definitions

Name Description
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 Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
CommunicationMessageKind

The type of message.
MediaNotificationContent

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.
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

Azure.Core.Foundations.Error

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

A response containing error details.

Name Type Description
error

Azure.Core.Foundations.Error

The error object.

Azure.Core.Foundations.InnerError

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name Type Description
code

string

One of a server-defined set of error codes.
innererror

Azure.Core.Foundations.InnerError

Inner error.

CommunicationMessageKind

The type of message.

Name Type Description
image

string

Image message type.
template

string

Template message type.
text

string

Text message type.

MediaNotificationContent

A request to send an image notification.

Name Type Description
channelRegistrationId

string

The Channel Registration ID for the Business Identifier.
content

string

Optional text content.
kind string:

image

The type discriminator describing a notification type.
mediaUri

string

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

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

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[]:

The template values.

MessageTemplateBindingsKind

The type of the message template.

Name Type Description
whatsApp

string

The WhatsApp template type.

MessageTemplateDocument

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

The (public) URL of the media.

MessageTemplateImage

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

The (public) URL of the media.

MessageTemplateLocation

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

The latitude of the location.
locationName

string

The [Optional] name of the location.
longitude

number

The longitude of the location.
name

string

Template binding reference name

MessageTemplateQuickAction

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

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

The type of the template parameter.

Name Type Description
document

string

The document template parameter type.
image

string

The image template parameter type.
location

string

The location template parameter type.
quickAction

string

The quick action template parameter type.
text

string

The text template parameter type.
video

string

The video template parameter type.

MessageTemplateVideo

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

The (public) URL of the media.

SendMessageResult

Result of the send message operation.

Name Type Description
receipts

MessageReceipt[]

Receipts of the send message operation.

TemplateNotificationContent

A request to send a template notification.

Name Type Description
channelRegistrationId

string

The Channel Registration ID for the Business Identifier.
kind string:

template

The type discriminator describing a notification type.
template

MessageTemplate

The template object used to create templates.
to

string[]

The native external platform user identifiers of the recipient.

TextNotificationContent

A request to send a text notification.

Name Type Description
channelRegistrationId

string

The Channel Registration ID for the Business Identifier.
content

string

Message content.
kind string:

text

The type discriminator describing a notification type.
to

string[]

The native external platform user identifiers of the recipient.

WhatsAppMessageButtonSubType

The WhatsApp button sub type.

Name Type Description
quickReply

string

The WhatsApp button sub type is quick reply.
url

string

The WhatsApp button sub type is url.

WhatsAppMessageTemplateBindings

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

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

The template bindings component for WhatsApp

Name Type Description
refValue

string

The name of the referenced item in the template values.