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.


GET/v1/messages

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.

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/messages

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

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
}

GET/v1/messages/:id

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

GET
/v1/messages/SIuAFUNKdSYHZF2w
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
}

PUT/v1/messages/:id

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

PUT
/v1/messages/SIuAFUNKdSYHZF2w
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
}

DELETE/v1/messages/:id

Delete a message

This endpoint allows you to delete messages from your conversations. Note: This will permanently delete the message.

Request

DELETE
/v1/messages/SIuAFUNKdSYHZF2w
curl -X DELETE https://api.protocol.chat/v1/messages/SIuAFUNKdSYHZF2w \
  -H "Authorization: Bearer {token}"