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/tracks/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
    query
    Type
    string
    Description

    Unique identifier for the other contact in the conversation.

  • Name
    ai
    Type
    boolean
    Description

    Unique identifier for the group that the conversation belongs to.

Request

POST
/v1/tracks/search
curl https://enterprise-api.tunetank.com/v1/tracks/search \
  -H "Authorization: Bearer {token}" \
  -d 'contact_id'="WAz8eIbvDR60rouK"

Response

{
  "count": 1
  "results": [{
    id: 1000,
    title: "Happy Day",
    artwork: "123",
    vocals: false,
    bpm: 114,
    locales: {
      ja: "幸せな一日"
    },
    durationMs: 102309,
    preview: "https://123",
    waveform: "https://123",
    themes: [1,2,3],
    genres: [1,2,3],
    moods: [1,2,3]
    tags: ["happy", "party"]
  }]
}
GET/v1/tracks

List all tracks

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/tracks
curl -G https://enterprise-api.tunetank.com/v1/tracks \
  -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/tracks/filters

List all filters

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/tracks/filters
curl https://enterprise-api.tunetank.com/v1/tracks/filters \
  -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/tracks/similar/:id

Similar tracks

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

GET
/v1/tracks/simiar/:id
curl https://api.protocol.chat/v1/conversations \
  -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": null,
  "last_opened_at": null,
  "created_at": 692233200,
  "archived_at": null
}
POST/v1/tracks/download/:id

Download a track

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
    id
    Type
    integer
    Description

    Unique identifier for the other contact in the conversation.

Request

POST
/v1/tracks/download/:id
curl https://enterprise-api.tunetank.com/v1/tracks/download/:id \
  -H "Authorization: Bearer {token}"

Response

{
  "mp3": "https://",
  "wav": "https://"
}
GET/v1/tracks/:id

Retrieve a track

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?