Messages
Messages are what conversations are made of in CityPay — they are the basic building blocks of your conversations with your CityPay 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 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
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
Request
curl -G https://api.protocol.chat/v1/messages \
-H "Authorization: Bearer {token}" \
-d conversation_id=xgQQXg3hrtjh7AvZ \
-d limit=10
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",
// ..
}
]
}
This endpoint allows you to send a new message to one of your conversations.
Required attributes
Optional attributes
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.’"
Response
{
"id": "gWqY86BMFRiH5o11",
"conversation_id": "xgQQXg3hrtjh7AvZ",
"contact": {
"id": "inEIRvzjC6YLMX3o",
"username": "LinnieMcCallister",
"phone_number": "1-800-759-3000",
"avatar_url": "https://assets.protocol.chat/avatars/linnie.jpg",
"last_active_at": 705103200,
"created_at": 692233200
},
"message": "You’re what the French call ‘les incompetents.’",
"reactions": [],
"attachments": [],
"read_at": null,
"created_at": 692233200,
"updated_at": null
}
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}"
Response
{
"id": "SIuAFUNKdSYHZF2w",
"conversation_id": "xgQQXg3hrtjh7AvZ",
"contact": {
"id": "WAz8eIbvDR60rouK",
"username": "KevinMcCallister",
"phone_number": "1-800-759-3000",
"avatar_url": "https://assets.protocol.chat/avatars/kevin.jpg",
"last_active_at": 705103200,
"created_at": 692233200
},
"message": "I’m traveling with my dad. He’s at a meeting. I hate meetings.",
"reactions": [],
"attachments": [],
"read_at": 705103200,
"created_at": 692233200,
"updated_at": 692233200
}
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
Request
curl -X PUT https://api.protocol.chat/v1/messages/SIuAFUNKdSYHZF2w \
-H "Authorization: Bearer {token}" \
-d 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": "I'm not apologizing. I'd rather kiss a toilet seat.",
"reactions": [
{
"red_angry_face": [
"KateMcCallister"
]
}
],
"attachments": [],
"read_at": 705103200,
"created_at": 692233200,
"updated_at": 692233200
}
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}"