GET
https://www.app.ocoya.com/api/_public/v1/inbox/conversations
List conversations
curl --request GET \
  --url https://www.app.ocoya.com/api/_public/v1/inbox/conversations \
  --header 'X-API-Key: <api-key>'
{
  "total": 42,
  "page": 0,
  "perPage": 25,
  "data": [
    {
      "id": "cmhx3v0k2000b7aps8q2u4n6e",
      "brandId": "cmayvq3hk00017apshay5qezu",
      "type": "DM",
      "status": "OPEN",
      "archived": false,
      "channel": {
        "id": "clh49poxf008x8kov4ncbjty9",
        "provider": "instagram",
        "name": "Ocoya"
      },
      "customer": {
        "name": "Ana García",
        "url": "https://www.instagram.com/anagarcia",
        "image": null,
        "language": "es"
      },
      "assigneeId": "clh49n2u300008kovd2wq1p8z",
      "labels": [
        {
          "id": "cmhx3w8hd000c7apsd1f0g2h3",
          "name": "Needs follow-up",
          "color": "#fa5252"
        }
      ],
      "unread": true,
      "lastMessage": {
        "id": "cmhx3x2pq000d7apsf4k5l6m7",
        "type": "received",
        "text": "Hi! Do you ship to Spain?",
        "images": [],
        "authorId": null,
        "deleted": false,
        "createdAt": "2024-01-01T00:00:00Z"
      },
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Authorizations

X-API-Keystringheaderrequired

Your API key. Create one in Ocoya. Authorization: Bearer <key> works too.

Query Parameters

brandIdstringrequired

Ocoya brand ID. Get one from GET /brands.

Example:"cmayvq3hk00017apshay5qezu"
statusenum<string>

Only conversations in this status.

Available options: OPEN, RESOLVED, SPAM
Example:"OPEN"
typeenum<string>

Only conversations of this kind.

Available options: DM, MENTION, COMMENT, REVIEW
Example:"DM"
channelIdsstring[]

Only conversations on these channels. Repeat the key for several.

Example:
[
  "clh49poxf008x8kov4ncbjty9"
]
labelIdsstring[]

Only conversations with any of these labels.

Example:
[
  "cmhx3w8hd000c7apsd1f0g2h3"
]
assigneeIdstring

Only conversations assigned to this teammate, or unassigned.

Example:"unassigned"
archivedboolean

true lists the archived conversations instead.

Example:false
querystring

The customer's name, or anything written in the conversation.

Example:"shipping"
pageinteger

Zero-based page number for paginated results.

Example:0
perPageinteger

Conversations per page, up to 100. Defaults to 25.

Required range: 1 <= x <= 100
Example:25

Response

application/json

Success

totalinteger

Conversations matching the filters.

Example:42
pageinteger
Example:0
perPageinteger
Example:25
dataobject[]

The page, the conversation with the newest message first.

Show child attributesHide child attributes
data.idstring

Conversation ID.

Example:"cmhx3v0k2000b7aps8q2u4n6e"
data.brandIdstring
Example:"cmayvq3hk00017apshay5qezu"
data.typeenum<string>

DM a private conversation (an email thread is one too), COMMENT a comment on the brand's post, MENTION a post that mentions the brand, REVIEW a Google review.

Available options: DM, MENTION, COMMENT, REVIEW
Example:"DM"
data.statusenum<string>

OPEN waiting for the team, RESOLVED done, SPAM junk. A new message from the customer reopens a resolved one.

Available options: OPEN, RESOLVED, SPAM
Example:"OPEN"
data.archivedboolean

Put away out of the inbox. The customer writing again brings it back.

Example:false
data.channelobject | null

The channel the conversation came in on.

Show child attributesHide child attributes
data.channel.idstring
Example:"clh49poxf008x8kov4ncbjty9"
data.channel.providerstring
Example:"instagram"
data.channel.namestring | null
Example:"Ocoya"
data.customerobject

Who the conversation is with.

Show child attributesHide child attributes
data.customer.namestring | null
Example:"Ana García"
data.customer.urlstring | null

Their profile, where the network gives one.

Example:"https://www.instagram.com/anagarcia"
data.customer.imagestring | null

Their profile picture.

data.customer.languagestring | null

The language they write in, as an ISO code.

Example:"es"
data.assigneeIdstring | null

The teammate it is assigned to. See GET /inbox/teammates.

Example:"clh49n2u300008kovd2wq1p8z"
data.labelsobject[]

Its labels.

Show child attributesHide child attributes
data.labels.idstring
Example:"cmhx3w8hd000c7apsd1f0g2h3"
data.labels.namestring
Example:"Needs follow-up"
data.labels.colorstring | null

CSS colour.

Example:"#fa5252"
data.unreadboolean

The customer wrote last, after the API key's user last opened it in Ocoya.

Example:true
data.lastMessageobject | null

The latest message or note.

Show child attributesHide child attributes
data.lastMessage.idstring

Message ID.

Example:"cmhx3x2pq000d7apsf4k5l6m7"
data.lastMessage.typeenum<string>

received from the customer, sent by the brand (a teammate, an automation or the API), note kept to the team.

Available options: received, sent, note
Example:"received"
data.lastMessage.textstring

What was written.

Example:"Hi! Do you ship to Spain?"
data.lastMessage.imagesstring[]

Image URLs attached to it.

Example:[]
data.lastMessage.authorIdstring | null

The teammate who wrote a note or sent a reply. Null for the customer and for automations.

data.lastMessage.deletedboolean

Deleted on the network. Kept so the conversation still reads in order.

Example:false
data.lastMessage.createdAtstring

When it was written.

Example:"2024-01-01T00:00:00Z"
data.createdAtstring

When the conversation started.

Example:"2024-01-01T00:00:00Z"