Namespace: microsoft.graph
Send a new chatMessage in the specified chat. This API can't create a new chat; you must use the list chats method to retrieve the ID of an existing chat before you can create a chat message.
Notes:
- We don't recommend that you use this API for data migration via the standard create message flow. For data migration scenarios, use the import messages flow instead.
- It's a violation of the terms of use to use Microsoft Teams as a log file. Only send messages that people will read.
This API is available in the following national cloud deployments.
| Global service |
US Government L4 |
US Government L5 (DOD) |
China operated by 21Vianet |
| ✅ |
✅ |
✅ |
✅ |
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
| Permission type |
Least privileged permissions |
Higher privileged permissions |
| Delegated (work or school account) |
ChatMessage.Send |
Chat.ReadWrite, Group.ReadWrite.All |
| Delegated (personal Microsoft account) |
Not supported. |
Not supported. |
| Application |
Teamwork.Migrate.All |
Not available. |
HTTP request
POST /chats/{chat-id}/messages
| Name |
Description |
| Authorization |
Bearer {code}. Required. |
Request body
In the request body, supply a JSON representation of a chatMessage object.
Response
If successful, this method returns a 201 Created response code and a new chatMessage object in the response body.
Examples
For a more comprehensive list of examples, see Create chatMessage in a channel or a chat.
Example 1: Create a chatMessage
Request
The following example shows a request.
POST https://graph.microsoft.com/v1.0/chats/19:2da4c29f6d7041eca70b638b43d45437@thread.v2/messages
Content-type: application/json
{
"body": {
"content": "Hello world"
}
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ChatMessage
{
Body = new ItemBody
{
Content = "Hello world",
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Chats["{chat-id}"].Messages.PostAsync(requestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewChatMessage()
body := graphmodels.NewItemBody()
content := "Hello world"
body.SetContent(&content)
requestBody.SetBody(body)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Chats().ByChatId("chat-id").Messages().Post(context.Background(), requestBody, nil)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ChatMessage chatMessage = new ChatMessage();
ItemBody body = new ItemBody();
body.setContent("Hello world");
chatMessage.setBody(body);
ChatMessage result = graphClient.chats().byChatId("{chat-id}").messages().post(chatMessage);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
const options = {
authProvider,
};
const client = Client.init(options);
const chatMessage = {
body: {
content: 'Hello world'
}
};
await client.api('/chats/19:2da4c29f6d7041eca70b638b43d45437@thread.v2/messages')
.post(chatMessage);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ChatMessage;
use Microsoft\Graph\Generated\Models\ItemBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ChatMessage();
$body = new ItemBody();
$body->setContent('Hello world');
$requestBody->setBody($body);
$result = $graphServiceClient->chats()->byChatId('chat-id')->messages()->post($requestBody)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Teams
$params = @{
body = @{
content = "Hello world"
}
}
New-MgChatMessage -ChatId $chatId -BodyParameter $params
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.chat_message import ChatMessage
from msgraph.generated.models.item_body import ItemBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ChatMessage(
body = ItemBody(
content = "Hello world",
),
)
result = await graph_client.chats.by_chat_id('chat-id').messages.post(request_body)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
The following example shows the response.
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#chats('19%3A2da4c29f6d7041eca70b638b43d45437%40thread.v2')/messages/$entity",
"id": "1616991463150",
"replyToId": null,
"etag": "1616991463150",
"messageType": "message",
"createdDateTime": "2021-03-29T04:17:43.15Z",
"lastModifiedDateTime": "2021-03-29T04:17:43.15Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": "19:2da4c29f6d7041eca70b638b43d45437@thread.v2",
"importance": "normal",
"locale": "en-us",
"webUrl": null,
"channelIdentity": null,
"policyViolation": null,
"eventDetail": null,
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser"
}
},
"body": {
"contentType": "text",
"content": "Hello World"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
}
Example 2: Import a message
The following example shows how to import a message. For more information, see Import messages into Microsoft Teams chats and channels using Microsoft Graph.
Note: The permission scope Teamwork.Migrate.All is required for this scenario. The target chat must be in migration mode.
Request
The following example shows how to import a message into a chat on behalf of a user using the createdDateTime and from properties in the request body.
POST https://graph.microsoft.com/v1.0/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/messages
{
"createdDateTime": "2019-02-04T19:58:15.511Z",
"from": {
"user": {
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser"
}
},
"body": {
"contentType": "html",
"content": "Hello World"
}
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ChatMessage
{
CreatedDateTime = DateTimeOffset.Parse("2019-02-04T19:58:15.511Z"),
From = new ChatMessageFromIdentitySet
{
User = new Identity
{
Id = "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
DisplayName = "Robin Kline",
AdditionalData = new Dictionary<string, object>
{
{
"userIdentityType" , "aadUser"
},
},
},
},
Body = new ItemBody
{
ContentType = BodyType.Html,
Content = "Hello World",
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Chats["{chat-id}"].Messages.PostAsync(requestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
"time"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewChatMessage()
createdDateTime , err := time.Parse(time.RFC3339, "2019-02-04T19:58:15.511Z")
requestBody.SetCreatedDateTime(&createdDateTime)
from := graphmodels.NewChatMessageFromIdentitySet()
user := graphmodels.NewIdentity()
id := "8ea0e38b-efb3-4757-924a-5f94061cf8c2"
user.SetId(&id)
displayName := "Robin Kline"
user.SetDisplayName(&displayName)
additionalData := map[string]interface{}{
"userIdentityType" : "aadUser",
}
user.SetAdditionalData(additionalData)
from.SetUser(user)
requestBody.SetFrom(from)
body := graphmodels.NewItemBody()
contentType := graphmodels.HTML_BODYTYPE
body.SetContentType(&contentType)
content := "Hello World"
body.SetContent(&content)
requestBody.SetBody(body)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Chats().ByChatId("chat-id").Messages().Post(context.Background(), requestBody, nil)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ChatMessage chatMessage = new ChatMessage();
OffsetDateTime createdDateTime = OffsetDateTime.parse("2019-02-04T19:58:15.511Z");
chatMessage.setCreatedDateTime(createdDateTime);
ChatMessageFromIdentitySet from = new ChatMessageFromIdentitySet();
Identity user = new Identity();
user.setId("8ea0e38b-efb3-4757-924a-5f94061cf8c2");
user.setDisplayName("Robin Kline");
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("userIdentityType", "aadUser");
user.setAdditionalData(additionalData);
from.setUser(user);
chatMessage.setFrom(from);
ItemBody body = new ItemBody();
body.setContentType(BodyType.Html);
body.setContent("Hello World");
chatMessage.setBody(body);
ChatMessage result = graphClient.chats().byChatId("{chat-id}").messages().post(chatMessage);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
const options = {
authProvider,
};
const client = Client.init(options);
const chatMessage = {
createdDateTime: '2019-02-04T19:58:15.511Z',
from: {
user: {
id: '8ea0e38b-efb3-4757-924a-5f94061cf8c2',
displayName: 'Robin Kline',
userIdentityType: 'aadUser'
}
},
body: {
contentType: 'html',
content: 'Hello World'
}
};
await client.api('/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/messages')
.post(chatMessage);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ChatMessage;
use Microsoft\Graph\Generated\Models\ChatMessageFromIdentitySet;
use Microsoft\Graph\Generated\Models\Identity;
use Microsoft\Graph\Generated\Models\ItemBody;
use Microsoft\Graph\Generated\Models\BodyType;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ChatMessage();
$requestBody->setCreatedDateTime(new \DateTime('2019-02-04T19:58:15.511Z'));
$from = new ChatMessageFromIdentitySet();
$fromUser = new Identity();
$fromUser->setId('8ea0e38b-efb3-4757-924a-5f94061cf8c2');
$fromUser->setDisplayName('Robin Kline');
$additionalData = [
'userIdentityType' => 'aadUser',
];
$fromUser->setAdditionalData($additionalData);
$from->setUser($fromUser);
$requestBody->setFrom($from);
$body = new ItemBody();
$body->setContentType(new BodyType('html'));
$body->setContent('Hello World');
$requestBody->setBody($body);
$result = $graphServiceClient->chats()->byChatId('chat-id')->messages()->post($requestBody)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Teams
$params = @{
createdDateTime = [System.DateTime]::Parse("2019-02-04T19:58:15.511Z")
from = @{
user = @{
id = "8ea0e38b-efb3-4757-924a-5f94061cf8c2"
displayName = "Robin Kline"
userIdentityType = "aadUser"
}
}
body = @{
contentType = "html"
content = "Hello World"
}
}
New-MgChatMessage -ChatId $chatId -BodyParameter $params
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.chat_message import ChatMessage
from msgraph.generated.models.chat_message_from_identity_set import ChatMessageFromIdentitySet
from msgraph.generated.models.identity import Identity
from msgraph.generated.models.item_body import ItemBody
from msgraph.generated.models.body_type import BodyType
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ChatMessage(
created_date_time = "2019-02-04T19:58:15.511Z",
from = ChatMessageFromIdentitySet(
user = Identity(
id = "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
display_name = "Robin Kline",
additional_data = {
"user_identity_type" : "aadUser",
}
),
),
body = ItemBody(
content_type = BodyType.Html,
content = "Hello World",
),
)
result = await graph_client.chats.by_chat_id('chat-id').messages.post(request_body)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
The following example shows the response.
HTTP/1.1 201 Created
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#chats('19%3A4b6bed8d24574f6a9e436813cb2617d8%40thread.tacv2')/messages/$entity",
"id": "1616991463150",
"replyToId": null,
"etag": "1616991463150",
"messageType": "message",
"createdDateTime": "2019-02-04T19:58:15.511Z",
"lastModifiedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": "19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2",
"importance": "normal",
"locale": "en-us",
"webUrl": null,
"channelIdentity": null,
"policyViolation": null,
"eventDetail": null,
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser"
}
},
"body": {
"contentType": "html",
"content": "Hello World"
},
"attachments": [],
"mentions": [],
"reactions": []
}