Shared shapes

The objects endpoints return — a conversation, a message, a contact… described once, here.

`Conversation`

A conversation: one person on one channel (WhatsApp), or one email thread.

idstring
The conversation id.
channelIdstring
The channel it lives on.
channelTypestring
The kind of channel.
whatsappemail
channelNamestring
The channel's name in Coplace.
statusstring
Where it stands.
openpendingclosed
subjectstring
Email subject; null elsewhere.
categorystring
The label key it is filed under, or null.
aiEnabledboolean
Whether the AI collaborator may answer in this conversation.
needsHumanboolean
Someone was asked to take over.
assignedUserIdstring
The member it is assigned to, or null.
agentNamestring
The collaborator's name on this conversation, or null.
contactobject
Who you are talking to.
Show fields
- idstring
  The contact id.
- displayNamestring
  Their name, or null.
- identitystring
  Their phone number (WhatsApp) or email address.
- identityKindstring
  What identity is.
  phoneemailexternal
- blockedboolean
  Blocked contacts are kept out of the inbox.
windowobject
The WhatsApp 24-hour customer service window.
Show fields
- appliesboolean
  false outside WhatsApp.
- openboolean
  Whether free text can be sent now. Always true when the rule does not apply.
- expiresAtstring
  When it closes, ISO 8601, or null.
- minutesLeftinteger
  Minutes left, 0 when closed, null when the rule does not apply.
unreadCountinteger
Messages from the contact not yet read by your team.
lastMessageAtstring
ISO 8601, or null.
lastInboundAtstring
When the contact last wrote, ISO 8601. This opens the 24-hour window.
createdAtstring
ISO 8601.
lastMessageobject
The latest message, or null.
Show fields
- idstring
  The message id.
- directionstring
  From the contact, or to them.
  inboundoutbound
- textContentstring
  Its text.
- statusstring
  Its delivery status.
- createdAtstring
  ISO 8601.

Conversation

Example

{  "id": "…",  "channelId": "…",  "channelType": "whatsapp",  "channelName": "…",  "status": "open",  "subject": "…",  "category": "…",  "aiEnabled": true,  "needsHuman": true,  "assignedUserId": "…",  "agentName": "…",  "contact": {    "id": "…",    "displayName": "…",    "identity": "…",    "identityKind": "phone",    "blocked": true  },  "window": {    "applies": true,    "open": true,    "expiresAt": "…",    "minutesLeft": 0  },  "unreadCount": 0,  "lastMessageAt": "…",  "lastInboundAt": "…",  "createdAt": "…",  "lastMessage": {    "id": "…",    "direction": "inbound",    "textContent": "…",    "status": "…",    "createdAt": "…"  }}

`Message`

One message, in either direction.

idstring
The message id.
conversationIdstring
Its conversation.
channelTypestring
The kind of channel.
whatsappemail
directionstring
inbound from the contact, outbound to them.
inboundoutbound
senderstring
Who speaks: the contact, the AI collaborator, your side (a person or your software), or Coplace.
contactagent_aiagent_humansystem
senderNamestring
The person's name, or your key's label.
apiKeyIdstring
The key that sent it, when it went through the API.
typestring
text, template, interactive, image, audio, document…
textContentstring
Its text. For a template, the rendered text.
transcriptstring
The text of a received voice note, when transcribed.
mediaUrlstring
Where to download its file (GET /inbox/messages/{id}/media), or null.
subjectstring
Email subject, or null.
statusstring
Delivery status. queued: waiting to leave (queue: true).
queuedsendingsentdeliveredreadfailed
providerMessageIdstring
The id at the messaging provider (WhatsApp wamid), or null.
errorstring
Why it failed, as the provider said, or null.
formobject
The buttons or list sent with it, or null.
replyobject
For a tapped button or chosen list row: { id, title }. Otherwise null.
locationobject
A location the contact sent: { latitude, longitude, name, address }, or null.
createdAtstring
ISO 8601.

Message

Example

{  "id": "…",  "conversationId": "…",  "channelType": "whatsapp",  "direction": "inbound",  "sender": "contact",  "senderName": "…",  "apiKeyId": "…",  "type": "…",  "textContent": "…",  "transcript": "…",  "mediaUrl": "…",  "subject": "…",  "status": "queued",  "providerMessageId": "…",  "error": "…",  "form": {},  "reply": {},  "location": {},  "createdAt": "…"}

`SendResult`

What a send returns.

messageMessage
duplicateboolean
true when this idempotencyKey was already used: the message returned is the first one, nothing was sent again.

SendResult

Example

{  "message": {    "id": "…",    "conversationId": "…",    "channelType": "whatsapp",    "direction": "inbound",    "sender": "contact",    "senderName": "…",    "apiKeyId": "…",    "type": "…",    "textContent": "…",    "transcript": "…",    "mediaUrl": "…",    "subject": "…",    "status": "queued",    "providerMessageId": "…",    "error": "…",    "form": {},    "reply": {},    "location": {},    "createdAt": "…"  },  "duplicate": true}

`Contact`

A person you talk to.

idstring
The contact id.
displayNamestring
Their name, or null.
localestring
Their language, e.g. fr, or null.
phonestring
Their phone number, E.164 digits, or null.
emailstring
Their email address, or null.
externalIdstring
Your own id for them, or null.
tagsstring[]
Free tags.
attributesobject
Custom field values, by attribute key.
optInAtstring
When they agreed to receive messages, or null.
optOutAtstring
When they withdrew — on WhatsApp by tapping "Stop" — or null. It overrides optInAt.
blockedboolean
Blocked contacts receive nothing.
conversationCountinteger
How many conversations they have.
lastMessageAtstring
ISO 8601, or null.
createdAtstring
ISO 8601.
updatedAtstring
ISO 8601.

Contact

Example

{  "id": "…",  "displayName": "…",  "locale": "…",  "phone": "…",  "email": "…",  "externalId": "…",  "tags": [    "…"  ],  "attributes": {},  "optInAt": "…",  "optOutAt": "…",  "blocked": true,  "conversationCount": 0,  "lastMessageAt": "…",  "createdAt": "…",  "updatedAt": "…"}

`ContactAttribute`

A custom field defined for contacts.

idstring
The attribute id.
keystring
The key used in attributes.
labelstring
Its name, in your words.
dataTypestring
text, number, boolean or date.
isArchivedboolean
Archived fields keep their values but are no longer shown.

ContactAttribute

Example

{ "id": "…", "key": "…", "label": "…", "dataType": "…", "isArchived": true}

`ContactNote`

A free-text note about a contact.

idstring
The note id.
bodystring
The note.
authorstring
The person's name or the key's label; null when the author no longer exists.
authorKindstring
Who wrote it.
userapi_key
createdAtstring
ISO 8601.

ContactNote

Example

{ "id": "…", "body": "…", "author": "…", "authorKind": "user", "createdAt": "…"}

`Channel`

A number or mailbox the workspace speaks from.

idstring
The channel id — the channelId you send from.
typestring
The kind of channel.
whatsappemail
namestring
Its name in Coplace.
identitystring
Its public identity: the business phone number id, or the mailbox address.
isActiveboolean
An inactive channel neither sends nor receives.
qualityRatingstring
WhatsApp quality rating: GREEN, YELLOW, RED, or null.
agentIdstring
The collaborator answering on it; null when your software answers.
messagingLimitstring
Meta's sending tier, or null.

Channel

Example

{  "id": "…",  "type": "whatsapp",  "name": "…",  "identity": "…",  "isActive": true,  "qualityRating": "…",  "agentId": "…",  "messagingLimit": "…"}

`Member`

A person of the workspace.

idstring
The member id — what assign takes.
fullNamestring
Their name.
emailstring
Their email address.
rolestring
Their role.
owneradminagentmember
canBeAssignedboolean
Whether a conversation can be assigned to them.

Member

Example

{ "id": "…", "fullName": "…", "email": "…", "role": "owner", "canBeAssigned": true}

`Template`

A WhatsApp message template.

idstring
The template id — the templateId you send.
namestring
Its name at Meta.
languagestring
Its language code, e.g. fr.
categorystring
Meta's category. Marketing ones are refused to contacts who opted out.
UTILITYMARKETINGAUTHENTICATION
statusstring
Only approved can be sent.
draftsubmittedapprovedrejectedpauseddisabled
bodystring
Its text, with {{1}}, {{2}}… placeholders.
rejectionReasonstring
Why Meta refused it, or null.
createdAtstring
ISO 8601.
updatedAtstring
ISO 8601.

Template

Example

{  "id": "…",  "name": "…",  "language": "…",  "category": "UTILITY",  "status": "draft",  "body": "…",  "rejectionReason": "…",  "createdAt": "…",  "updatedAt": "…"}

`WebhookSubscription`

An address Coplace calls, and for which events.

idstring
The subscription id.
urlstring
The https address called.
eventsstring[]
The events delivered; * means all.
labelstring
Its name.
isActiveboolean
A paused subscription receives nothing.
lastDeliveredAtstring
The last successful call, ISO 8601, or null.
lastErrorstring
What went wrong last time, or null.
previousSecretValidUntilstring
During a rotation: until when the old secret still signs. null otherwise.
createdAtstring
ISO 8601.

WebhookSubscription

Example

{  "id": "…",  "url": "…",  "events": [    "…"  ],  "label": "…",  "isActive": true,  "lastDeliveredAt": "…",  "lastError": "…",  "previousSecretValidUntil": "…",  "createdAt": "…"}

`WebhookDelivery`

One event delivered — or to deliver — to one subscription.

idstring
The delivery id, also sent as X-Coplace-Delivery.
subscriptionIdstring
The subscription.
eventstring
The event name.
eventIdstring
The event's own id (evt_…), the same across redeliveries: deduplicate on it.
statusstring
failed after six attempts.
pendingdeliveredfailed
attemptsinteger
Attempts so far.
responseStatusinteger
The HTTP status your server answered, or null.
lastErrorstring
What went wrong, or null.
nextAttemptAtstring
When the next attempt is due, for a pending delivery.
createdAtstring
ISO 8601.
deliveredAtstring
ISO 8601, or null.

WebhookDelivery

Example

{  "id": "…",  "subscriptionId": "…",  "event": "…",  "eventId": "…",  "status": "pending",  "attempts": 0,  "responseStatus": 0,  "lastError": "…",  "nextAttemptAt": "…",  "createdAt": "…",  "deliveredAt": "…"}

`ApiRequest`

One call made with an API key.

idstring
The log line id.
apiKeyIdstring
The key used.
keyLabelstring
The key's label.
keyPrefixstring
The key's public prefix, cop_….
methodstring
HTTP method.
pathstring
The address called, without its query string.
statusinteger
The HTTP status returned.
errorCodestring
The error code returned, or null.
durationMsinteger
How long it took.
requestIdstring
The request id, also returned in errors.
createdAtstring
ISO 8601.

ApiRequest

Example

{  "id": "…",  "apiKeyId": "…",  "keyLabel": "…",  "keyPrefix": "…",  "method": "…",  "path": "…",  "status": 0,  "errorCode": "…",  "durationMs": 0,  "requestId": "…",  "createdAt": "…"}

`Error`

Every refusal of `/api/v1`.

errorobject
What went wrong.
Show fields
- statusinteger
  The HTTP status, repeated.
- codestring
  A stable code. Test this, never the text.
- messagestring
  What it means, in English.
- detailstring
  The specific reason, when there is one. May be in French.
- requestIdstring
  Quote it to us if you need help.
- dataobject
  Extra facts attached to some refusals (e.g. issues).

Error

Example

{  "error": {    "status": 0,    "code": "…",    "message": "…",    "detail": "…",    "requestId": "…",    "data": {}  }}