Messages
Messages are what conversations are made of in Protocol — they are the basic building blocks of your conversations with your Protocol contacts. On this page, we'll dive into the different message endpoints you can use to manage messages programmatically. We'll look at how to query, send, update, and delete messages.
The message model
The message model contains all the information about the messages and attachments you send to your contacts and groups, including how your contacts have reacted to them.
Properties
-
- Name
id- Type
- string
- Description
-
Unique identifier for the message.
-
- Name
conversation_id- Type
- string
- Description
-
Unique identifier for the conversation the message belongs to.
-
- Name
contact- Type
- object
- Description
-
The contact object for the contact who sent the message.
-
- Name
message- Type
- string
- Description
-
The message content.
-
- Name
reactions- Type
- array
- Description
-
An array of reaction objects associated with the message.
-
- Name
attachments- Type
- array
- Description
-
An array of attachment objects associated with the message.
-
- Name
read_at- Type
- timestamp
- Description
-
Timestamp of when the message was read.
-
- Name
created_at- Type
- timestamp
- Description
-
Timestamp of when the message was created.
-
- Name
updated_at- Type
- timestamp
- Description
-
Timestamp of when the message was last updated.
List all messages
This endpoint allows you to retrieve a paginated list of all your messages (in a conversation if a conversation id is provided). By default, a maximum of ten messages are shown per page.
Optional attributes
-
- Name
conversation_id- Type
- string
- Description
-
Limit to messages from a given conversation.
-
- Name
limit- Type
- integer
- Description
-
Limit the number of messages returned.
true.
Request
curl -G https://api.protocol.chat/v1/messages \
-H "Authorization: Bearer {token}" \
-d conversation_id=xgQQXg3hrtjh7AvZ \
-d limit=10
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.messages.list()
from protocol_api import ApiClient
client = ApiClient(token)
client.messages.list()
$client = new \Protocol\ApiClient($token);
$client->messages->list();
Response
{
"has_more": false,
"data": [
{
"id": "SIuAFUNKdSYHZF2w"
"conversation_id": "xgQQXg3hrtjh7AvZ",
"contact": {
"id": "WAz8eIbvDR60rouK",
"username": "KevinMcCallister",
"phone_number": "1-800-759-3000",
"avatar_url": "https://assets.protocol.chat/avatars/buzzboy.jpg",
"last_active_at": 705103200,
"created_at": 692233200
},
"message": "It’s a nice night for a neck injury.",
"reactions": [],
"attachments": [],
"read_at": 705103200,
"created_at": 692233200,
"updated_at": 692233200
},
{
"id": "hSIhXBhNe8X1d8Et"
// ...
}
]
}
Send a message
This endpoint allows you to send a new message to one of your conversations.
Required attributes
-
- Name
conversation_id- Type
- string
- Description
-
Unique identifier for the conversation the message belongs to.
-
- Name
message- Type
- string
- Description
-
The message content.
Optional attributes
-
- Name
attachments- Type
- array
- Description
-
An array of attachment objects associated with the message.
Request
curl https://api.protocol.chat/v1/messages \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d message="You’re what the French call ‘les incompetents.’"
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.messages.create({
conversation_id: 'xgQQXg3hrtjh7AvZ',
message: 'You’re what the French call ‘les incompetents.’',
})
from protocol_api import ApiClient
client = ApiClient(token)
client.messages.send(
conversation_id="xgQQXg3hrtjh7AvZ",
message="You’re what the French call ‘les incompetents.’",
)
$client = new \Protocol\ApiClient($token);
$client->messages->create([
'conversation_id' => 'xgQQXg3hrtjh7AvZ',
'message' => 'You’re what the French call ‘les incompetents.’',
]);
Response
{
"id": "SIuAFUNKdSYHZF2w"
"conversation_id": "xgQQXg3hrtjh7AvZ",
"contact": {
"id": "WAz8eIbvDR60rouK",
"username": "KevinMcCallister",
"phone_number": "1-800-759-3000",
"avatar_url": "https://assets.protocol.chat/avatars/buzzboy.jpg",
"last_active_at": 705103200,
"created_at": 692233200
},
"message": "It’s a nice night for a neck injury.",
"reactions": [],
"attachments": [],
"read_at": 705103200,
"created_at": 692233200,
"updated_at": 692233200
},
Retrieve a message
This endpoint allows you to retrieve a message by providing the message id. Refer to the list at the top of this page to see which properties are included with message objects.
Request
curl https://api.protocol.chat/v1/messages/SIuAFUNKdSYHZF2w \
-H "Authorization: Bearer {token}" \
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.messages.get('SIuAFUNKdSYHZF2w')
from protocol_api import ApiClient
client = ApiClient(token)
client.messages.get("SIuAFUNKdSYHZF2w")
$client = new \Protocol\ApiClient($token);
$client->messages->get('SIuAFUNKdSYHZF2w');
Response
{
"id": "SIuAFUNKdSYHZF2w"
"conversation_id": "xgQQXg3hrtjh7AvZ",
"contact": {
"id": "WAz8eIbvDR60rouK",
"username": "KevinMcCallister",
"phone_number": "1-800-759-3000",
"avatar_url": "https://assets.protocol.chat/avatars/buzzboy.jpg",
"last_active_at": 705103200,
"created_at": 692233200
},
"message": "It’s a nice night for a neck injury.",
"reactions": [],
"attachments": [],
"read_at": 705103200,
"created_at": 692233200,
"updated_at": 692233200
},
Update a message
This endpoint allows you to perform an update on a message. Examples of updates are adding a reaction, editing the message, or adding an attachment.
Optional attributes
-
- Name
message- Type
- string
- Description
-
The message content.
-
- Name
reactions- Type
- array
- Description
-
An array of reaction objects associated with the message.
-
- Name
attachments- Type
- array
- Description
-
An array of attachment objects associated with the message.
Request
curl -X PUT https://api.protocol.chat/v1/messages/SIuAFUNKdSYHZF2w \
-H "Authorization: Bearer {token}" \
-d reactions[red_angry_face][]="KateMcCallister"
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.messages.update('SIuAFUNKdSYHZF2w', {
reactions: {
red_angry_face: ['KateMcCallister']
}
})
from protocol_api import ApiClient
client = ApiClient(token)
client.messages.update("SIuAFUNKdSYHZF2w",
reactions={"red_angry_face": ["KateMcCallister"]})
$client = new \Protocol\ApiClient($token);
$client->messages->update('SIuAFUNKdSYHZF2w', [
'reactions' => [
'red_angry_face' => ['KateMcCallister'],
],
]);
Response
{
"id": "SIuAFUNKdSYHZF2w"
"conversation_id": "xgQQXg3hrtjh7AvZ",
"contact": {
"id": "WAz8eIbvDR60rouK",
"username": "KevinMcCallister",
"phone_number": "1-800-759-3000",
"avatar_url": "https://assets.protocol.chat/avatars/buzzboy.jpg",
"last_active_at": 705103200,
"created_at": 692233200
},
"message": "It’s a nice night for a neck injury.",
"reactions": [
{
"red_angry_face": [
"KateMcCallister"
]
}
],
"attachments": [],
"read_at": 705103200,
"created_at": 692233200,
"updated_at": 692233200
},
Delete a message
This endpoint allows you to delete messages from your conversations. Note: This will permanently delete the message.
Request
curl -X DELETE https://api.protocol.chat/v1/messages/SIuAFUNKdSYHZF2w \
-H "Authorization: Bearer {token}"
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.messages.delete('SIuAFUNKdSYHZF2w')
from protocol_api import ApiClient
client = ApiClient(token)
client.messages.delete("SIuAFUNKdSYHZF2w")
$client = new \Protocol\ApiClient($token);
$client->messages->delete('SIuAFUNKdSYHZF2w');