curl --request POST \
--url https://{your-subdomain}.neetochat.com/api/external/v2/conversations/{conversation_id}/messages \
--header 'Accept: <accept>' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <x-api-key>' \
--data '
{
"body": "Thanks, we have processed your refund.",
"sender_email": "oliver@example.com",
"kind": "user_message",
"mentions": [
{
"email": "jane@example.com"
}
]
}
'const options = {
method: 'POST',
headers: {
'X-Api-Key': '<x-api-key>',
Accept: '<accept>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
body: JSON.stringify('Thanks, we have processed your refund.'),
sender_email: 'oliver@example.com',
kind: 'user_message',
mentions: [{email: 'jane@example.com'}]
})
};
fetch('https://{your-subdomain}.neetochat.com/api/external/v2/conversations/{conversation_id}/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{your-subdomain}.neetochat.com/api/external/v2/conversations/{conversation_id}/messages"
payload = {
"body": "Thanks, we have processed your refund.",
"sender_email": "oliver@example.com",
"kind": "user_message",
"mentions": [{ "email": "jane@example.com" }]
}
headers = {
"X-Api-Key": "<x-api-key>",
"Accept": "<accept>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"message": {
"id": "1bf689fc-9f92-4e39-9f71-4a97078d2b8f",
"body": "<p>Thanks, we have processed your refund.</p>",
"kind": "user_message",
"status": "read",
"created_at": "2026-10-05T16:26:57.912Z",
"updated_at": "2026-10-05T16:26:57.912Z",
"sender": {
"id": "05665eee-4602-4317-8f7f-767b04274e5f",
"name": "Oliver Smith",
"email": "oliver@example.com",
"type": "User"
},
"attachments": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "invoice.pdf",
"content_type": "application/pdf",
"url": "https://spinkart.neetochat.com/rails/active_storage/blobs/redirect/.../invoice.pdf"
}
],
"message_gif": null
}
}{
"error": "Conversation does not exist."
}{
"error": "Only agents can add notes. sender_email must belong to an agent."
}Send message
Add a message or an internal note to a conversation.
The sender is resolved from sender_email. If it belongs to an active team member, the message is sent as a reply from that team member. Otherwise it is sent as a message from the contact with that email, and a new contact is created when none exists.
curl --request POST \
--url https://{your-subdomain}.neetochat.com/api/external/v2/conversations/{conversation_id}/messages \
--header 'Accept: <accept>' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <x-api-key>' \
--data '
{
"body": "Thanks, we have processed your refund.",
"sender_email": "oliver@example.com",
"kind": "user_message",
"mentions": [
{
"email": "jane@example.com"
}
]
}
'const options = {
method: 'POST',
headers: {
'X-Api-Key': '<x-api-key>',
Accept: '<accept>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
body: JSON.stringify('Thanks, we have processed your refund.'),
sender_email: 'oliver@example.com',
kind: 'user_message',
mentions: [{email: 'jane@example.com'}]
})
};
fetch('https://{your-subdomain}.neetochat.com/api/external/v2/conversations/{conversation_id}/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{your-subdomain}.neetochat.com/api/external/v2/conversations/{conversation_id}/messages"
payload = {
"body": "Thanks, we have processed your refund.",
"sender_email": "oliver@example.com",
"kind": "user_message",
"mentions": [{ "email": "jane@example.com" }]
}
headers = {
"X-Api-Key": "<x-api-key>",
"Accept": "<accept>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"message": {
"id": "1bf689fc-9f92-4e39-9f71-4a97078d2b8f",
"body": "<p>Thanks, we have processed your refund.</p>",
"kind": "user_message",
"status": "read",
"created_at": "2026-10-05T16:26:57.912Z",
"updated_at": "2026-10-05T16:26:57.912Z",
"sender": {
"id": "05665eee-4602-4317-8f7f-767b04274e5f",
"name": "Oliver Smith",
"email": "oliver@example.com",
"type": "User"
},
"attachments": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "invoice.pdf",
"content_type": "application/pdf",
"url": "https://spinkart.neetochat.com/rails/active_storage/blobs/redirect/.../invoice.pdf"
}
],
"message_gif": null
}
}{
"error": "Conversation does not exist."
}{
"error": "Only agents can add notes. sender_email must belong to an agent."
}{your-subdomain} with your workspace’s subdomain. Learn how to find your subdomain in Workspace subdomain.
Headers
Use the X-Api-Key header to provide your workspace API key. Refer to Authentication for more information.
Specifies the expected response format. Must be set to application/json for proper API communication.
application/json Path Parameters
Id of the conversation. You can get conversation_id by listing conversations using our List conversations API.
"de414e85-a1b5-4240-a465-7b32606980ce"
Body
Content of the message.
"Thanks, we have processed your refund."
Email of the team member or contact sending the message. A note must be sent by an active team member.
"oliver@example.com"
Pass note to add an internal note that only team members can see.
user_message, note Team members to mention in a note. Mentions are only supported when kind is note. Each @Name in the body that matches a mentioned team member becomes a mention, and team members not named in the body are mentioned at the end of the note.
Hide child attributes
Hide child attributes
"jane@example.com"
Response
Created - Message added successfully
Hide child attributes
Hide child attributes
"1bf689fc-9f92-4e39-9f71-4a97078d2b8f"
Content of the message. It may contain HTML.
"<p>Thanks, we have processed your refund.</p>"
Type of the message. user_message is a chat message and note is an internal note that only team members can see. Other kinds, such as system_message and activity_message, are created by NeetoChat.
"user_message"
"read"
"2026-10-05T16:26:57.912Z"
"2026-10-05T16:26:57.912Z"
Hide child attributes
Hide child attributes
"05665eee-4602-4317-8f7f-767b04274e5f"
"Oliver Smith"
"oliver@example.com"
User for a team member and Insights::Visitor for a contact.
"User"