Share via

Conversation Thread Operations - Send Message

Service:
Communication
API Version:
2025-04-01-preview

Sends a conversation message from Business to User.

POST {endpoint}/messages/conversations/{conversationId}/messages:send?api-version=2025-04-01-preview

URI Parameters

Name In Required Type Description
conversationId
 path True

string

The conversation ID.
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 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

Name Required Type Description
request True ConversationMessageContent:

Details of a send conversation message request.
outboundDeliveryStrategy

OutboundDeliveryStrategyKind

The options of the outbound delivery strategy for messages sent by participants in a conversation. Supports internalOnly, allChannels.

Responses

Name Type Description
200 OK

SendConversationMessageResult

The request has succeeded.

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 conversation message from Business to User

Sample request

POST https://my-resource.communication.azure.com/messages/conversations/19:34adfa4f-cedf-4dc0-ba29-b6d1a69ab345@thread.v2/messages:send?api-version=2025-04-01-preview

{
  "request": {
    "kind": "text",
    "content": "I need help"
  },
  "outboundDeliveryStrategy": "allParticipants"
}

Sample response

Status code:
200 
{
  "messageId": "1593107077690"
}

Definitions

Name Description
AudioConversationMessageContent

A request to send an audio conversation message.
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/azure/Guidelines.md#handling-errors.
CommunicationMessageKind

The type of message.
DocumentConversationMessageContent

A request to send a document conversation message.
ImageConversationMessageContent

A request to send an image conversation 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.
OutboundDeliveryStrategyKind

The options of the outbound delivery strategy for messages sent by participants in a conversation.
SendConversationMessageOptions

Request payload for sending a conversation message.
SendConversationMessageResult

Result of the send conversation message operation.
TemplateConversationMessageContent

A request to send a template conversation message.
TextConversationMessageContent

A request to send a text conversation message.
VideoConversationMessageContent

A request to send a video conversation message.
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

AudioConversationMessageContent

Object

A request to send an audio conversation message.

Name Type Description
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

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 Microsoft One API guidelines - https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#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.
sticker

Sticker message type.
reaction

Reaction message type.
interactive

Interactive Actionable message type.

DocumentConversationMessageContent

Object

A request to send a document conversation message.

Name Type Description
caption

string

Optional text content.
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

ImageConversationMessageContent

Object

A request to send an image conversation message.

Name Type Description
caption

string

Optional text content.
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

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

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.

OutboundDeliveryStrategyKind

Enumeration

The options of the outbound delivery strategy for messages sent by participants in a conversation.

Value Description
internalOnly

Delivery strategy for internal only.
allParticipants

Delivery strategy for all participants.

SendConversationMessageOptions

Object

Request payload for sending a conversation message.

Name Type Description
outboundDeliveryStrategy

OutboundDeliveryStrategyKind

The options of the outbound delivery strategy for messages sent by participants in a conversation. Supports internalOnly, allChannels.
request ConversationMessageContent:

Details of a send conversation message request.

SendConversationMessageResult

Object

Result of the send conversation message operation.

Name Type Description
messageId

string

A server-generated Advanced Messaging conversation message id.

TemplateConversationMessageContent

Object

A request to send a template conversation message.

Name Type Description
kind string:

template

The type discriminator describing a message type.
template

MessageTemplate

The template object used to create templates.

TextConversationMessageContent

Object

A request to send a text conversation message.

Name Type Description
content

string

Message content.
kind string:

text

The type discriminator describing a message type.

VideoConversationMessageContent

Object

A request to send a video conversation message.

Name Type Description
caption

string

Optional text content.
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

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.