Conversations
Guest and owner messaging across SMS, email, and in-app channels.
12 endpoints. Every request needs an Authorization: Bearer mtro_... header, and responses follow the envelope described in Errors and conventions.
POST /conversations/add-message
Add an internal/in-app conversation message. External delivery should use conversations_send_message and require owner confirmation.
Required scope: conversations.write
MCP tool: conversations_add_message
Request body
Field names are taken from the Core handler, which reads exactly these. Types and which of them are required are not yet documented.
| Field | Type | Required | Description |
|---|---|---|---|
attachments | any | no | |
clientMessageId | any | no | |
conversationId | any | no | |
message | any | no |
Example
curl -X POST 'https://core.mtro.app/conversations/add-message' \
-H 'Authorization: Bearer mtro_your_api_key' \
-H 'Content-Type: application/json' \
-d '{}'
POST /conversations/create
Create a conversation. This may start guest-facing communication and should require owner confirmation when used by an agent.
Required scope: conversations.write
MCP tool: conversations_create
Request body
Field names are taken from the Core handler, which reads exactly these. Types and which of them are required are not yet documented.
| Field | Type | Required | Description |
|---|---|---|---|
contactEmail | any | no | |
contactName | any | no | |
contactPhone | any | no | |
conversationScope | any | no | |
entityId | any | no | |
entityOwner | any | no | |
entityType | any | no | |
guestId | any | no | |
message | any | no | |
participants | any | no | |
subject | any | no |
Example
curl -X POST 'https://core.mtro.app/conversations/create' \
-H 'Authorization: Bearer mtro_your_api_key' \
-H 'Content-Type: application/json' \
-d '{}'
POST /conversations/delete-message/{conversationId}/{messageId}
Delete an owner-authored message. This is destructive and should require owner confirmation when used by an agent.
Required scope: conversations.write
MCP tool: conversations_delete_message
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
conversationId | string | yes | Conversation ID. |
messageId | string | yes | Message ID. |
Example
curl -X POST 'https://core.mtro.app/conversations/delete-message/<conversationId>/<messageId>' \
-H 'Authorization: Bearer mtro_your_api_key'
POST /conversations/edit-message/{conversationId}/{messageId}
Edit an owner-authored message. This writes account data and should require owner confirmation when used by an agent.
Required scope: conversations.write
MCP tool: conversations_edit_message
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
conversationId | string | yes | Conversation ID. |
messageId | string | yes | Message ID. |
Request body
A JSON object. This endpoint's fields are not documented yet — send the same body the admin panel sends, or ask MTRO PRO for the field list.
Example
curl -X POST 'https://core.mtro.app/conversations/edit-message/<conversationId>/<messageId>' \
-H 'Authorization: Bearer mtro_your_api_key' \
-H 'Content-Type: application/json' \
-d '{}'
POST /conversations/get
List owner conversations. Supports Core /conversations/get filters through payload. For a booking, pass payload.bookingRef or payload.bookingId to return the booking conversation directly.
Required scope: conversations.read
MCP tool: conversations_list
Request body
Field names are taken from the Core handler, which reads exactly these. Types and which of them are required are not yet documented.
| Field | Type | Required | Description |
|---|---|---|---|
conversationScope | any | no | |
entityType | any | no | |
limit | any | no | |
page | any | no | |
search | any | no | |
status | any | no |
Example
curl -X POST 'https://core.mtro.app/conversations/get' \
-H 'Authorization: Bearer mtro_your_api_key' \
-H 'Content-Type: application/json' \
-d '{}'
Response
| Field | Type |
|---|---|
conversations | any[] |
total | integer |
page | integer |
limit | integer |
error | boolean |
GET /conversations/get/{conversationId}
Get a conversation by ID, including messages.
Required scope: conversations.read
MCP tool: conversations_get
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
conversationId | string | yes | Conversation ID. |
Example
curl -X GET 'https://core.mtro.app/conversations/get/<conversationId>' \
-H 'Authorization: Bearer mtro_your_api_key'
GET /conversations/get/entity/{entityId}
Get conversations for an entity.
Required scope: conversations.read
MCP tool: conversations_get_by_entity, conversations_list
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
entityId | string | yes | Entity ID. |
Example
curl -X GET 'https://core.mtro.app/conversations/get/entity/<entityId>' \
-H 'Authorization: Bearer mtro_your_api_key'
Response
| Field | Type |
|---|---|
conversations | any[] |
error | boolean |
POST /conversations/mark-read/{conversationId}
Mark a conversation read.
Required scope: conversations.read
MCP tool: conversations_mark_read
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
conversationId | string | yes | Conversation ID. |
Example
curl -X POST 'https://core.mtro.app/conversations/mark-read/<conversationId>' \
-H 'Authorization: Bearer mtro_your_api_key'
POST /conversations/mark-unread/{conversationId}
Mark a conversation unread.
Required scope: conversations.read
MCP tool: conversations_mark_unread
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
conversationId | string | yes | Conversation ID. |
Example
curl -X POST 'https://core.mtro.app/conversations/mark-unread/<conversationId>' \
-H 'Authorization: Bearer mtro_your_api_key'
POST /conversations/retry-message/{conversationId}/{messageId}
Retry delivery of a failed conversation message. This may send external communication and should require owner confirmation when used by an agent.
Required scope: conversations.write
MCP tool: conversations_retry_message
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
conversationId | string | yes | Conversation ID. |
messageId | string | yes | Message ID. |
Example
curl -X POST 'https://core.mtro.app/conversations/retry-message/<conversationId>/<messageId>' \
-H 'Authorization: Bearer mtro_your_api_key'
POST /conversations/send-message
Send a message through email or SMS. This sends external communication and should require owner confirmation when used by an agent. Required final Core payload is conversationId, channel, and message. Convenience: instead of conversationId, pass bookingRef or bookingId and the MCP will find or create the booking guest conversation first.
Required scope: conversations.write
MCP tool: conversations_send_message
Example
curl -X POST 'https://core.mtro.app/conversations/send-message' \
-H 'Authorization: Bearer mtro_your_api_key'
POST /conversations/update
Update conversation metadata or status. This writes account data and should require owner confirmation when used by an agent.
Required scope: conversations.write
MCP tool: conversations_update
Request body
Field names are taken from the Core handler, which reads exactly these. Types and which of them are required are not yet documented.
| Field | Type | Required | Description |
|---|---|---|---|
conversationId | any | no | |
status | any | no |
Example
curl -X POST 'https://core.mtro.app/conversations/update' \
-H 'Authorization: Bearer mtro_your_api_key' \
-H 'Content-Type: application/json' \
-d '{}'