PATCH
https://www.app.ocoya.com/api/_public/v1/inbox/conversations/{conversationId}
Update a conversation
curl --request PATCH \
  --url https://www.app.ocoya.com/api/_public/v1/inbox/conversations/{conversationId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "status": "RESOLVED",
  "archived": false,
  "assigneeId": "clh49n2u300008kovd2wq1p8z",
  "labelIds": [
    "cmhx3w8hd000c7apsd1f0g2h3"
  ]
}
'
{
  "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.

Path Parameters

conversationIdstringrequired

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

Example:"cmhx3v0k2000b7aps8q2u4n6e"

Body

application/json
statusenum<string>

RESOLVED to close it, OPEN to reopen it, SPAM to mark it as junk.

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

true archives it, false moves it back to the inbox.

Example:false
assigneeIdstring | null

A teammate's user ID from GET /inbox/teammates, or null to unassign it.

Example:"clh49n2u300008kovd2wq1p8z"
labelIdsstring[]

Its labels from now on, replacing the ones it has. [] removes them all. IDs from GET /inbox/labels.

Example:
[
  "cmhx3w8hd000c7apsd1f0g2h3"
]

Response

application/json

The conversation as it is now.

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"