Tracks

Conversations are an essential part of Protocol — they are the containers for the messages between you, your contacts, and groups. On this page, we’ll dive into the different conversation endpoints you can use to manage conversations programmatically. We'll look at how to query, create, update, and delete conversations.

GET/v1/sfx/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/sfx

List all sound effects

This endpoint allows you to retrieve a paginated list of all tracks in catalog. By default, a maximum of 50 tracks are shown per page.

Optional attributes

  • Name
    limit
    Type
    integer
    Description

    Limit the number of conversations returned.

  • Name
    muted
    Type
    boolean
    Description

    Only show conversations that are muted when set to true.

  • Name
    archived
    Type
    boolean
    Description

    Only show conversations that are archived when set to true.

  • Name
    pinned
    Type
    boolean
    Description

    Only show conversations that are pinned when set to true.

  • Name
    group_id
    Type
    string
    Description

    Only show conversations for the specified group.

Request

GET
/v1/conversations
curl -G https://api.protocol.chat/v1/conversations \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "id": "xgQQXg3hrtjh7AvZ",
      "contact_id": "WAz8eIbvDR60rouK",
      "group_id": null,
      "pinned_message_id": null,
      "is_pinned": false,
      "is_muted": false,
      "last_active_at": 705103200,
      "last_opened_at": 705103200,
      "created_at": 692233200,
      "archived_at": null
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}
GET/v1/sfx/tags

List all tags

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/sfx/similar/:id

Similar sounds

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
}
POST/v1/sfx/download/

Download a sound

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/sfx/sound/:id

Retrieve a sound

This endpoint allows you to retrieve a conversation by providing the conversation id. Refer to the list at the top of this page to see which properties are included with conversation objects.

Request

GET
/v1/conversations/xgQQXg3hrtjh7AvZ
curl https://api.protocol.chat/v1/conversations/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"

Response

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

Was this page helpful?