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.

GET/v1/sfx/search

Search

This endpoint allows you to add a new conversation between you and a contact or group. A contact or group id is required to create a conversation.

Required attributes

Name
contact_id
Type
string
Description
Unique identifier for the other contact in the conversation.
Name
group_id
Type
string
Description
Unique identifier for the group that the conversation belongs to.

Request

POST

/v1/conversations

curl https://api.protocol.chat/v1/conversations \
  -H "Authorization: Bearer {token}" \
  -d 'contact_id'="WAz8eIbvDR60rouK"

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "contact_id": "WAz8eIbvDR60rouK",
  "group_id": null,
  "pinned_message_id": null,
  "is_pinned": false,
  "is_muted": false,
  "last_active_at": null,
  "last_opened_at": null,
  "created_at": 692233200,
  "archived_at": null
}

GET/v1/playlists

List all playlists

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.

Request

GET

/v1/messages

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",
      // ..
    }
  ]
}

POST/v1/playlists/themes

List all themes

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

POST

/v1/messages

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
}