GET
https://www.app.ocoya.com/api/_public/v1/inbox/conversations/{conversationId}
Get a conversation
curl --request GET \
  --url https://www.app.ocoya.com/api/_public/v1/inbox/conversations/{conversationId} \
  --header 'X-API-Key: <api-key>'
{
  "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",
  "messages": [
    {
      "id": "cmhx3x2pq000d7apsf4k5l6m7",
      "type": "received",
      "text": "Hi! Do you ship to Spain?",
      "images": [],
      "authorId": null,
      "deleted": false,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Authorizations

X-API-Keystringheaderrequired

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

Path Parameters

conversationIdstringrequired

Conversation ID. Get one from GET /inbox/conversations.

Example:"cmhx3v0k2000b7aps8q2u4n6e"

Query Parameters

limitinteger

How many of the latest messages to return, up to 200. Defaults to 50.

Required range: 1 <= x <= 200
Example:50

Response

application/json

Success

idstring

Conversation ID.

Example:"cmhx3v0k2000b7aps8q2u4n6e"
brandIdstring
Example:"cmayvq3hk00017apshay5qezu"
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"
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"
archivedboolean

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

Example:false
channelobject | null

The channel the conversation came in on.

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

Who the conversation is with.

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

Their profile, where the network gives one.

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

Their profile picture.

customer.languagestring | null

The language they write in, as an ISO code.

Example:"es"
assigneeIdstring | null

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

Example:"clh49n2u300008kovd2wq1p8z"
labelsobject[]

Its labels.

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

CSS colour.

Example:"#fa5252"
unreadboolean

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

Example:true
lastMessageobject | null

The latest message or note.

Show child attributesHide child attributes
lastMessage.idstring

Message ID.

Example:"cmhx3x2pq000d7apsf4k5l6m7"
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"
lastMessage.textstring

What was written.

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

Image URLs attached to it.

Example:[]
lastMessage.authorIdstring | null

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

lastMessage.deletedboolean

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

Example:false
lastMessage.createdAtstring

When it was written.

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

When the conversation started.

Example:"2024-01-01T00:00:00Z"
messagesobject[]

The latest messages and notes, oldest first.

Show child attributesHide child attributes
messages.idstring

Message ID.

Example:"cmhx3x2pq000d7apsf4k5l6m7"
messages.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"
messages.textstring

What was written.

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

Image URLs attached to it.

Example:[]
messages.authorIdstring | null

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

messages.deletedboolean

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

Example:false
messages.createdAtstring

When it was written.

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