Multichannel communication APIs for adding voice, video, chat, SMS, and email to applications.
openapi: 3.1.0
info:
title: Microsoft Azure Communication Services API
description: >-
Multichannel communication APIs for adding voice, video, chat, SMS, and
email capabilities to applications.
version: '2024-03-15'
contact:
name: Azure Communication Services Support
url: https://learn.microsoft.com/en-us/azure/communication-services/
termsOfService: https://www.microsoft.com/en-us/legal/terms-of-use
externalDocs:
description: Azure Communication Services REST API Reference
url: https://learn.microsoft.com/en-us/rest/api/communication/
servers:
- url: https://{resource}.communication.azure.com
description: Azure Communication Services Endpoint
variables:
resource:
default: your-resource
description: Your Communication Services resource name
tags:
- name: Chat
description: Manage chat threads and messages
- name: Email
description: Send email messages
- name: Identity
description: Create and manage communication identities
- name: SMS
description: Send SMS messages
security:
- accessKey: []
paths:
/identities:
post:
operationId: createIdentity
summary: Microsoft Create an identity
description: Create a new Communication Services identity.
tags:
- Identity
parameters:
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
createTokenWithScopes:
type: array
items:
type: string
enum:
- chat
- voip
description: Also create an access token with these scopes
responses:
'201':
description: Identity created
content:
application/json:
schema:
$ref: '#/components/schemas/CommunicationIdentityAccessTokenResult'
'401':
description: Unauthorized
/identities/{id}:
delete:
operationId: deleteIdentity
summary: Microsoft Delete an identity
description: Delete a Communication Services identity and revoke all tokens.
tags:
- Identity
parameters:
- name: id
in: path
required: true
description: Identifier of the identity to delete
schema:
type: string
- $ref: '#/components/parameters/apiVersion'
responses:
'204':
description: Identity deleted
'401':
description: Unauthorized
'404':
description: Identity not found
/identities/{id}/:issueAccessToken:
post:
operationId: issueAccessToken
summary: Microsoft Issue an access token
description: Issue a new access token for an identity.
tags:
- Identity
parameters:
- name: id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- scopes
properties:
scopes:
type: array
items:
type: string
enum:
- chat
- voip
expiresInMinutes:
type: integer
minimum: 60
maximum: 1440
default: 1440
responses:
'200':
description: Access token issued
content:
application/json:
schema:
$ref: '#/components/schemas/CommunicationIdentityAccessToken'
'401':
description: Unauthorized
/sms:
post:
operationId: sendSms
summary: Microsoft Send an SMS message
description: Send a single SMS message or a batch of SMS messages.
tags:
- SMS
parameters:
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendSmsRequest'
responses:
'202':
description: SMS accepted for delivery
content:
application/json:
schema:
$ref: '#/components/schemas/SmsSendResult'
'400':
description: Invalid request
'401':
description: Unauthorized
/emails:send:
post:
operationId: sendEmail
summary: Microsoft Send an email
description: Queues an email message for sending.
tags:
- Email
parameters:
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmailMessage'
responses:
'202':
description: Email accepted for delivery
headers:
Operation-Location:
schema:
type: string
description: URL to poll for send status
content:
application/json:
schema:
type: object
properties:
id:
type: string
status:
type: string
enum:
- NotStarted
- Running
- Succeeded
- Failed
- Canceled
'400':
description: Invalid request
'401':
description: Unauthorized
/chat/threads:
post:
operationId: createChatThread
summary: Microsoft Create a chat thread
description: Create a new chat thread.
tags:
- Chat
parameters:
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChatThreadRequest'
responses:
'201':
description: Chat thread created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChatThreadResult'
'400':
description: Invalid request
'401':
description: Unauthorized
get:
operationId: listChatThreads
summary: Microsoft List chat threads
description: List all chat threads for the authenticated user.
tags:
- Chat
parameters:
- $ref: '#/components/parameters/apiVersion'
- name: maxPageSize
in: query
description: Maximum number of threads per page
schema:
type: integer
- name: startTime
in: query
description: Start time for the range query
schema:
type: string
format: date-time
responses:
'200':
description: List of chat threads
content:
application/json:
schema:
type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/ChatThread'
nextLink:
type: string
'401':
description: Unauthorized
/chat/threads/{chatThreadId}/messages:
post:
operationId: sendChatMessage
summary: Microsoft Send a chat message
description: Send a message to a chat thread.
tags:
- Chat
parameters:
- name: chatThreadId
in: path
required: true
description: Chat thread ID
schema:
type: string
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- content
properties:
content:
type: string
senderDisplayName:
type: string
type:
type: string
enum:
- text
- html
default: text
responses:
'201':
description: Message sent
content:
application/json:
schema:
type: object
properties:
id:
type: string
'400':
description: Invalid request
'401':
description: Unauthorized
get:
operationId: listChatMessages
summary: Microsoft List chat messages
description: List messages in a chat thread.
tags:
- Chat
parameters:
- name: chatThreadId
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/apiVersion'
- name: maxPageSize
in: query
schema:
type: integer
- name: startTime
in: query
schema:
type: string
format: date-time
responses:
'200':
description: List of messages
content:
application/json:
schema:
type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/ChatMessageItem'
nextLink:
type: string
'401':
description: Unauthorized
components:
securitySchemes:
accessKey:
type: apiKey
name: Authorization
in: header
description: HMAC-SHA256 signature authentication
parameters:
apiVersion:
name: api-version
in: query
required: true
description: API version
schema:
type: string
default: '2024-03-15-preview'
schemas:
CommunicationIdentityAccessTokenResult:
type: object
properties:
identity:
type: object
properties:
id:
type: string
accessToken:
$ref: '#/components/schemas/CommunicationIdentityAccessToken'
CommunicationIdentityAccessToken:
type: object
properties:
token:
type: string
expiresOn:
type: string
format: date-time
SendSmsRequest:
type: object
required:
- from
- smsRecipients
- message
properties:
from:
type: string
description: Sender phone number in E.164 format
smsRecipients:
type: array
items:
type: object
required:
- to
properties:
to:
type: string
description: Recipient phone number in E.164 format
message:
type: string
description: The message body (max 2048 characters)
maxLength: 2048
smsSendOptions:
type: object
properties:
enableDeliveryReport:
type: boolean
default: false
tag:
type: string
SmsSendResult:
type: object
properties:
value:
type: array
items:
type: object
properties:
to:
type: string
messageId:
type: string
httpStatusCode:
type: integer
successful:
type: boolean
errorMessage:
type: string
EmailMessage:
type: object
required:
- senderAddress
- recipients
- content
properties:
senderAddress:
type: string
description: Sender email address
recipients:
type: object
required:
- to
properties:
to:
type: array
items:
type: object
required:
- address
properties:
address:
type: string
displayName:
type: string
cc:
type: array
items:
type: object
properties:
address:
type: string
displayName:
type: string
bcc:
type: array
items:
type: object
properties:
address:
type: string
displayName:
type: string
content:
type: object
required:
- subject
properties:
subject:
type: string
plainText:
type: string
html:
type: string
CreateChatThreadRequest:
type: object
required:
- topic
properties:
topic:
type: string
participants:
type: array
items:
type: object
required:
- communicationIdentifier
properties:
communicationIdentifier:
type: object
properties:
communicationUserId:
type: string
displayName:
type: string
CreateChatThreadResult:
type: object
properties:
chatThread:
$ref: '#/components/schemas/ChatThread'
errors:
type: object
ChatThread:
type: object
properties:
id:
type: string
topic:
type: string
createdOn:
type: string
format: date-time
createdByCommunicationIdentifier:
type: object
properties:
communicationUserId:
type: string
deletedOn:
type: string
format: date-time
ChatMessageItem:
type: object
properties:
id:
type: string
type:
type: string
content:
type: object
properties:
message:
type: string
senderDisplayName:
type: string
createdOn:
type: string
format: date-time
senderCommunicationIdentifier:
type: object
properties:
communicationUserId:
type: string