{ "openapi": "3.1.0", "info": { "title": "Coplace API", "version": "v1", "description": "Coplace connects a business's own software to its customers on WhatsApp and email.\n\nThis API gives your software everything it needs: send and receive messages, manage contacts and approved templates, subscribe to webhooks, and hand conversations to — or take them back from — the AI collaborator.\n\nEvery call is scoped to one workspace: the key decides which one, and nothing crosses over.\n\nEvery success is `{ \"data\": … }`; every refusal is `{ \"error\": { \"status\", \"code\", \"message\", \"detail\", \"requestId\" } }`. Test `error.code`, never the text." }, "servers": [ { "url": "https://coplace.io/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "components": { "schemas": { "Conversation": { "type": "object", "description": "A conversation: one person on one channel (WhatsApp), or one email thread.", "properties": { "id": { "type": "string", "description": "The conversation id." }, "channelId": { "type": "string", "description": "The channel it lives on." }, "channelType": { "type": "string", "description": "The kind of channel.", "enum": [ "whatsapp", "email" ] }, "channelName": { "type": "string", "description": "The channel's name in Coplace." }, "status": { "type": "string", "description": "Where it stands.", "enum": [ "open", "pending", "closed" ] }, "subject": { "type": "string", "description": "Email subject; `null` elsewhere." }, "category": { "type": "string", "description": "The label key it is filed under, or `null`." }, "aiEnabled": { "type": "boolean", "description": "Whether the AI collaborator may answer in this conversation." }, "needsHuman": { "type": "boolean", "description": "Someone was asked to take over." }, "assignedUserId": { "type": "string", "description": "The member it is assigned to, or `null`." }, "agentName": { "type": "string", "description": "The collaborator's name on this conversation, or `null`." }, "contact": { "type": "object", "description": "Who you are talking to.", "properties": { "id": { "type": "string", "description": "The contact id." }, "displayName": { "type": "string", "description": "Their name, or `null`." }, "identity": { "type": "string", "description": "Their phone number (WhatsApp) or email address." }, "identityKind": { "type": "string", "description": "What `identity` is.", "enum": [ "phone", "email", "external" ] }, "blocked": { "type": "boolean", "description": "Blocked contacts are kept out of the inbox." } } }, "window": { "type": "object", "description": "The WhatsApp 24-hour customer service window.", "properties": { "applies": { "type": "boolean", "description": "`false` outside WhatsApp." }, "open": { "type": "boolean", "description": "Whether free text can be sent now. Always `true` when the rule does not apply." }, "expiresAt": { "type": "string", "description": "When it closes, ISO 8601, or `null`." }, "minutesLeft": { "type": "integer", "description": "Minutes left, `0` when closed, `null` when the rule does not apply." } } }, "unreadCount": { "type": "integer", "description": "Messages from the contact not yet read by your team." }, "lastMessageAt": { "type": "string", "description": "ISO 8601, or `null`." }, "lastInboundAt": { "type": "string", "description": "When the contact last wrote, ISO 8601. This opens the 24-hour window." }, "createdAt": { "type": "string", "description": "ISO 8601." }, "lastMessage": { "type": "object", "description": "The latest message, or `null`.", "properties": { "id": { "type": "string", "description": "The message id." }, "direction": { "type": "string", "description": "From the contact, or to them.", "enum": [ "inbound", "outbound" ] }, "textContent": { "type": "string", "description": "Its text." }, "status": { "type": "string", "description": "Its delivery status." }, "createdAt": { "type": "string", "description": "ISO 8601." } } } } }, "Message": { "type": "object", "description": "One message, in either direction.", "properties": { "id": { "type": "string", "description": "The message id." }, "conversationId": { "type": "string", "description": "Its conversation." }, "channelType": { "type": "string", "description": "The kind of channel.", "enum": [ "whatsapp", "email" ] }, "direction": { "type": "string", "description": "`inbound` from the contact, `outbound` to them.", "enum": [ "inbound", "outbound" ] }, "sender": { "type": "string", "description": "Who speaks: the contact, the AI collaborator, your side (a person or your software), or Coplace.", "enum": [ "contact", "agent_ai", "agent_human", "system" ] }, "senderName": { "type": "string", "description": "The person's name, or your key's label." }, "apiKeyId": { "type": "string", "description": "The key that sent it, when it went through the API." }, "type": { "type": "string", "description": "`text`, `template`, `interactive`, `image`, `audio`, `document`…" }, "textContent": { "type": "string", "description": "Its text. For a template, the rendered text." }, "transcript": { "type": "string", "description": "The text of a received voice note, when transcribed." }, "mediaUrl": { "type": "string", "description": "Where to download its file (`GET /inbox/messages/{id}/media`), or `null`." }, "subject": { "type": "string", "description": "Email subject, or `null`." }, "status": { "type": "string", "description": "Delivery status. `queued`: waiting to leave (`queue: true`).", "enum": [ "queued", "sending", "sent", "delivered", "read", "failed" ] }, "providerMessageId": { "type": "string", "description": "The id at the messaging provider (WhatsApp `wamid`), or `null`." }, "error": { "type": "string", "description": "Why it failed, as the provider said, or `null`." }, "form": { "type": "object", "description": "The buttons or list sent with it, or `null`." }, "reply": { "type": "object", "description": "For a tapped button or chosen list row: `{ id, title }`. Otherwise `null`." }, "location": { "type": "object", "description": "A location the contact sent: `{ latitude, longitude, name, address }`, or `null`." }, "createdAt": { "type": "string", "description": "ISO 8601." } } }, "SendResult": { "type": "object", "description": "What a send returns.", "properties": { "message": { "$ref": "#/components/schemas/Message" }, "duplicate": { "type": "boolean", "description": "`true` when this `idempotencyKey` was already used: the message returned is the first one, nothing was sent again." } } }, "Contact": { "type": "object", "description": "A person you talk to.", "properties": { "id": { "type": "string", "description": "The contact id." }, "displayName": { "type": "string", "description": "Their name, or `null`." }, "locale": { "type": "string", "description": "Their language, e.g. `fr`, or `null`." }, "phone": { "type": "string", "description": "Their phone number, E.164 digits, or `null`." }, "email": { "type": "string", "description": "Their email address, or `null`." }, "externalId": { "type": "string", "description": "Your own id for them, or `null`." }, "tags": { "type": "array", "description": "Free tags.", "items": { "type": "string", "description": "A tag." } }, "attributes": { "type": "object", "description": "Custom field values, by attribute key." }, "optInAt": { "type": "string", "description": "When they agreed to receive messages, or `null`." }, "optOutAt": { "type": "string", "description": "When they withdrew — on WhatsApp by tapping \"Stop\" — or `null`. It overrides `optInAt`." }, "blocked": { "type": "boolean", "description": "Blocked contacts receive nothing." }, "conversationCount": { "type": "integer", "description": "How many conversations they have." }, "lastMessageAt": { "type": "string", "description": "ISO 8601, or `null`." }, "createdAt": { "type": "string", "description": "ISO 8601." }, "updatedAt": { "type": "string", "description": "ISO 8601." } } }, "ContactAttribute": { "type": "object", "description": "A custom field defined for contacts.", "properties": { "id": { "type": "string", "description": "The attribute id." }, "key": { "type": "string", "description": "The key used in `attributes`." }, "label": { "type": "string", "description": "Its name, in your words." }, "dataType": { "type": "string", "description": "`text`, `number`, `boolean` or `date`." }, "isArchived": { "type": "boolean", "description": "Archived fields keep their values but are no longer shown." } } }, "ContactNote": { "type": "object", "description": "A free-text note about a contact.", "properties": { "id": { "type": "string", "description": "The note id." }, "body": { "type": "string", "description": "The note." }, "author": { "type": "string", "description": "The person's name or the key's label; `null` when the author no longer exists." }, "authorKind": { "type": "string", "description": "Who wrote it.", "enum": [ "user", "api_key" ] }, "createdAt": { "type": "string", "description": "ISO 8601." } } }, "Channel": { "type": "object", "description": "A number or mailbox the workspace speaks from.", "properties": { "id": { "type": "string", "description": "The channel id — the `channelId` you send from." }, "type": { "type": "string", "description": "The kind of channel.", "enum": [ "whatsapp", "email" ] }, "name": { "type": "string", "description": "Its name in Coplace." }, "identity": { "type": "string", "description": "Its public identity: the business phone number id, or the mailbox address." }, "isActive": { "type": "boolean", "description": "An inactive channel neither sends nor receives." }, "qualityRating": { "type": "string", "description": "WhatsApp quality rating: `GREEN`, `YELLOW`, `RED`, or `null`." }, "agentId": { "type": "string", "description": "The collaborator answering on it; `null` when your software answers." }, "messagingLimit": { "type": "string", "description": "Meta's sending tier, or `null`." } } }, "Member": { "type": "object", "description": "A person of the workspace.", "properties": { "id": { "type": "string", "description": "The member id — what `assign` takes." }, "fullName": { "type": "string", "description": "Their name." }, "email": { "type": "string", "description": "Their email address." }, "role": { "type": "string", "description": "Their role.", "enum": [ "owner", "admin", "agent", "member" ] }, "canBeAssigned": { "type": "boolean", "description": "Whether a conversation can be assigned to them." } } }, "Template": { "type": "object", "description": "A WhatsApp message template.", "properties": { "id": { "type": "string", "description": "The template id — the `templateId` you send." }, "name": { "type": "string", "description": "Its name at Meta." }, "language": { "type": "string", "description": "Its language code, e.g. `fr`." }, "category": { "type": "string", "description": "Meta's category. Marketing ones are refused to contacts who opted out.", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ] }, "status": { "type": "string", "description": "Only `approved` can be sent.", "enum": [ "draft", "submitted", "approved", "rejected", "paused", "disabled" ] }, "body": { "type": "string", "description": "Its text, with `{{1}}`, `{{2}}`… placeholders." }, "rejectionReason": { "type": "string", "description": "Why Meta refused it, or `null`." }, "createdAt": { "type": "string", "description": "ISO 8601." }, "updatedAt": { "type": "string", "description": "ISO 8601." } } }, "WebhookSubscription": { "type": "object", "description": "An address Coplace calls, and for which events.", "properties": { "id": { "type": "string", "description": "The subscription id." }, "url": { "type": "string", "description": "The https address called." }, "events": { "type": "array", "description": "The events delivered; `*` means all.", "items": { "type": "string", "description": "An event name." } }, "label": { "type": "string", "description": "Its name." }, "isActive": { "type": "boolean", "description": "A paused subscription receives nothing." }, "lastDeliveredAt": { "type": "string", "description": "The last successful call, ISO 8601, or `null`." }, "lastError": { "type": "string", "description": "What went wrong last time, or `null`." }, "previousSecretValidUntil": { "type": "string", "description": "During a rotation: until when the old secret still signs. `null` otherwise." }, "createdAt": { "type": "string", "description": "ISO 8601." } } }, "WebhookDelivery": { "type": "object", "description": "One event delivered — or to deliver — to one subscription.", "properties": { "id": { "type": "string", "description": "The delivery id, also sent as `X-Coplace-Delivery`." }, "subscriptionId": { "type": "string", "description": "The subscription." }, "event": { "type": "string", "description": "The event name." }, "eventId": { "type": "string", "description": "The event's own id (`evt_…`), the same across redeliveries: deduplicate on it." }, "status": { "type": "string", "description": "`failed` after six attempts.", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer", "description": "Attempts so far." }, "responseStatus": { "type": "integer", "description": "The HTTP status your server answered, or `null`." }, "lastError": { "type": "string", "description": "What went wrong, or `null`." }, "nextAttemptAt": { "type": "string", "description": "When the next attempt is due, for a pending delivery." }, "createdAt": { "type": "string", "description": "ISO 8601." }, "deliveredAt": { "type": "string", "description": "ISO 8601, or `null`." } } }, "ApiRequest": { "type": "object", "description": "One call made with an API key.", "properties": { "id": { "type": "string", "description": "The log line id." }, "apiKeyId": { "type": "string", "description": "The key used." }, "keyLabel": { "type": "string", "description": "The key's label." }, "keyPrefix": { "type": "string", "description": "The key's public prefix, `cop_…`." }, "method": { "type": "string", "description": "HTTP method." }, "path": { "type": "string", "description": "The address called, without its query string." }, "status": { "type": "integer", "description": "The HTTP status returned." }, "errorCode": { "type": "string", "description": "The error `code` returned, or `null`." }, "durationMs": { "type": "integer", "description": "How long it took." }, "requestId": { "type": "string", "description": "The request id, also returned in errors." }, "createdAt": { "type": "string", "description": "ISO 8601." } } }, "Error": { "type": "object", "description": "Every refusal of `/api/v1`.", "properties": { "error": { "type": "object", "description": "What went wrong.", "properties": { "status": { "type": "integer", "description": "The HTTP status, repeated." }, "code": { "type": "string", "description": "A stable code. Test this, never the text." }, "message": { "type": "string", "description": "What it means, in English." }, "detail": { "type": "string", "description": "The specific reason, when there is one. May be in French." }, "requestId": { "type": "string", "description": "Quote it to us if you need help." }, "data": { "type": "object", "description": "Extra facts attached to some refusals (e.g. `issues`)." } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Send `Authorization: Bearer cop_…`. A key belongs to ONE workspace and acts as itself, not as the person who created it: removing that person does not revoke the key, and messages it sends are attributed to the key's label." } } }, "paths": { "/api-requests": { "get": { "tags": [ "API keys" ], "summary": "List recent API calls", "description": "Every call made to `/api/v1` with one of this workspace's keys over the last 30 days: method, address, status, error code and duration. Newest first. Use it to see why a call failed without asking us.\n\nNeither bodies, headers nor query strings are kept. A call refused because the key itself was wrong is not listed: we cannot tell whose it was.\n\nRequires a key with the `admin` role or above.", "operationId": "getApiV1ApiRequests", "responses": { "200": { "description": "A page of calls, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "A page of calls.", "properties": { "items": { "type": "array", "description": "The calls.", "items": { "$ref": "#/components/schemas/ApiRequest" } }, "nextCursor": { "type": "string", "description": "Pass it as `cursor` for the next page; `null` at the end." }, "hasMore": { "type": "boolean", "description": "Whether another page exists." } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "apiKeyId", "in": "query", "required": false, "description": "Only calls made with this key.", "schema": { "type": "string", "description": "Only calls made with this key." } }, { "name": "errorsOnly", "in": "query", "required": false, "description": "`true` keeps only calls that did not succeed (status 400 and above).", "schema": { "type": "boolean", "description": "`true` keeps only calls that did not succeed (status 400 and above)." } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100. Default 50.", "schema": { "type": "integer", "description": "Page size, 1 to 100. Default 50." } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page.", "schema": { "type": "string", "description": "The `nextCursor` of the previous page." } } ] } }, "/inbox/channels": { "get": { "tags": [ "Channels" ], "summary": "List the channels of the workspace", "description": "Returns every WhatsApp number and mailbox the workspace can speak from, with the identifier you need everywhere else. **Start here**: opening a conversation requires a `channelId`, and there is no other way to obtain one.\n\nA channel that is switched off still appears, with `isActive: false`. Nothing is sent or received on it until someone switches it back on in Coplace.", "operationId": "getApiV1InboxChannels", "responses": { "200": { "description": "The channels, each with its id, type, public identity, and whether it is active.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The channels.", "properties": { "items": { "type": "array", "description": "The channels.", "items": { "$ref": "#/components/schemas/Channel" } } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "description": "Returns the people this workspace has talked to, searchable by name, phone number or email. Custom attributes come back alongside, so you can map them into your own records.", "operationId": "getApiV1Contacts", "responses": { "200": { "description": "A page of contacts, and the attribute definitions that describe their custom fields.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "A page of contacts.", "properties": { "items": { "type": "array", "description": "The contacts.", "items": { "$ref": "#/components/schemas/Contact" } }, "attributes": { "type": "array", "description": "The custom field definitions.", "items": { "$ref": "#/components/schemas/ContactAttribute" } }, "nextCursor": { "type": "string", "description": "Pass it as `cursor` for the next page; `null` at the end." }, "total": { "type": "integer", "description": "How many match, on the first page only; `null` after." } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search by name, phone number or email.", "schema": { "type": "string", "description": "Search by name, phone number or email." } }, { "name": "limit", "in": "query", "required": false, "description": "How many to return.", "schema": { "type": "integer", "description": "How many to return." } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string", "description": "Opaque cursor from the previous page." } } ] }, "post": { "tags": [ "Contacts" ], "summary": "Create a contact", "description": "Creates someone before they have written. A contact needs at least one identity — a phone number or an email address — otherwise nothing can ever reach them.\n\nIf that identity is already known, the existing contact is returned rather than duplicated.\n\nRequires a key with the `agent` role or above.", "operationId": "postApiV1Contacts", "responses": { "200": { "description": "The contact.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The contact and how to read its custom fields.", "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "attributes": { "type": "array", "description": "The custom field definitions.", "items": { "$ref": "#/components/schemas/ContactAttribute" } } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`no_identity` — Neither a phone number nor an email address was given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fullName": { "type": "string", "description": "Their name, as you want it displayed." }, "phone": { "type": "string", "description": "Phone number in E.164 form.", "example": "+33612345678" }, "email": { "type": "string", "description": "Email address." }, "attributes": { "type": "object", "description": "Your custom fields, by key. See `GET /contacts/attributes`." } }, "required": [] } } } } } }, "/contacts/{id}": { "get": { "tags": [ "Contacts" ], "summary": "Get one contact", "description": "Returns the contact with all their identities and custom attributes.", "operationId": "getApiV1ContactsId}", "responses": { "200": { "description": "The contact, and the attribute definitions describing their custom fields.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The contact and how to read its custom fields.", "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "attributes": { "type": "array", "description": "The custom field definitions.", "items": { "$ref": "#/components/schemas/ContactAttribute" } } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "string", "description": "The contact id." } } ] }, "patch": { "tags": [ "Contacts" ], "summary": "Update a contact", "description": "Changes the name or the custom attributes. Fields you leave out keep their value.\n\nIdentities — phone numbers and email addresses — are not edited here: they are established by real conversations, and rewriting them would silently merge two people.\n\nRequires a key with the `agent` role or above.", "operationId": "patchApiV1ContactsId}", "responses": { "200": { "description": "The contact, updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The contact and how to read its custom fields.", "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "attributes": { "type": "array", "description": "The custom field definitions.", "items": { "$ref": "#/components/schemas/ContactAttribute" } } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "string", "description": "The contact id." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fullName": { "type": "string", "description": "Their name." }, "attributes": { "type": "object", "description": "Custom fields to set, by key." } }, "required": [] } } } } } }, "/contacts/{id}/notes": { "get": { "tags": [ "Contacts" ], "summary": "List notes on a contact", "description": "Free-text notes your team or your software wrote about this person, newest first. Notes are never shown to the contact and never read by the collaborator.", "operationId": "getApiV1ContactsIdNotes", "responses": { "200": { "description": "The notes, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The notes.", "properties": { "items": { "type": "array", "description": "Up to 200 notes, newest first.", "items": { "$ref": "#/components/schemas/ContactNote" } } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "string", "description": "The contact id." } } ] }, "post": { "tags": [ "Contacts" ], "summary": "Add a note to a contact", "description": "Writes a free-text note about this person — what your CRM knows, a call summary, a warning for the team. It is signed with your key's label. The contact never sees it.\n\nRequires a key with the `agent` role or above.", "operationId": "postApiV1ContactsIdNotes", "responses": { "200": { "description": "The note.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ContactNote" } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "string", "description": "The contact id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The note, 1 to 5000 characters." } }, "required": [ "body" ] } } } } } }, "/contacts/{id}/notes/{noteId}": { "delete": { "tags": [ "Contacts" ], "summary": "Delete a note", "description": "Deletes a note. Only its author — the same key, or the same person — or an `admin` key can.\n\nRequires a key with the `agent` role or above.", "operationId": "deleteApiV1ContactsIdNotesNoteId}", "responses": { "200": { "description": "Confirmation that it is gone.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Confirmation.", "properties": { "deleted": { "type": "boolean", "description": "Always `true`." } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "string", "description": "The contact id." } }, { "name": "noteId", "in": "path", "required": true, "description": "The note id.", "schema": { "type": "string", "description": "The note id." } } ] } }, "/contacts/attributes": { "get": { "tags": [ "Contacts" ], "summary": "List the custom contact fields", "description": "Returns the fields this account defined on its contacts: their key, label and type. Read this before writing `attributes` on a contact — an unknown key is refused.\n\nThese belong to the account, so every workspace of the same client shares them.", "operationId": "getApiV1ContactsAttributes", "responses": { "200": { "description": "The attribute definitions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The custom field definitions.", "properties": { "items": { "type": "array", "description": "The definitions.", "items": { "$ref": "#/components/schemas/ContactAttribute" } } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/privacy/contacts/{id}": { "delete": { "tags": [ "Contacts" ], "summary": "Erase a person, for good", "description": "**Irreversible.** Deletes the contact, their identities, their messages and their conversations. Meant for a right-to-erasure request.\n\nWhat is kept is what carries no personal data: counters, and the record that an erasure happened. The call returns a report of what was removed.\n\nRequires a key with the `admin` role or above.", "operationId": "deleteApiV1PrivacyContactsId}", "responses": { "200": { "description": "A report: what was erased, and how much of it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "What was erased.", "properties": { "erased": { "type": "boolean", "description": "Always `true`." }, "removed": { "type": "object", "description": "Counts removed: `identities`, `conversations`, `messages`." }, "emptied": { "type": "object", "description": "Counts kept for deduplication but emptied of their content." } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "string", "description": "The contact id." } } ] } }, "/inbox/categories": { "get": { "tags": [ "Conversations" ], "summary": "List the labels of the inbox", "description": "Labels are how threads are actually sorted — more than the open/closed state. A label can also keep its threads out of the queue (`skipProcedure`); what the AI collaborator does lives on the procedure each thread follows.\n\nRequires a key with the `admin` role or above.", "operationId": "getApiV1InboxCategories", "responses": { "200": { "description": "The labels, with their name and colour.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The labels.", "properties": { "items": { "type": "array", "description": "The labels.", "items": { "type": "object", "description": "A label.", "properties": { "key": { "type": "string", "description": "What `category` holds on a conversation." }, "name": { "type": "string", "description": "Its name." }, "color": { "type": "string", "description": "Its colour." }, "skipProcedure": { "type": "boolean", "description": "The procedure skips these threads: out of the queue at reception." } } } }, "counts": { "type": "object", "description": "Conversations per label key over the last 30 days." } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inbox/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversations", "description": "Returns conversations, most recently active first, with a cursor for the next page.\n\nFilters combine. `folder` picks the view (default `inbox`); `mine` and `starred` are personal and refused for a key (422 `personal_folder`) — a key is not a person. Trial conversations are excluded unless `folder=trials` or `sandbox` says otherwise. Counts per folder, label and channel: `GET /inbox/overview`.", "operationId": "getApiV1InboxConversations", "responses": { "200": { "description": "A page of conversations and the cursor for the next one.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "A page of conversations.", "properties": { "items": { "type": "array", "description": "The conversations, most recent activity first.", "items": { "$ref": "#/components/schemas/Conversation" } }, "nextCursor": { "type": "string", "description": "Pass it as `cursor` for the next page; `null` at the end." }, "hasMore": { "type": "boolean", "description": "Whether another page exists." }, "total": { "type": "integer", "description": "How many match, on the first page only; `null` after." } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many to return, 100 at most. Defaults to 50.", "schema": { "type": "integer", "description": "How many to return, 100 at most. Defaults to 50." } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page. Omit for the first page.", "schema": { "type": "string", "description": "Opaque cursor from the previous page. Omit for the first page." } }, { "name": "folder", "in": "query", "required": false, "description": "The view. Defaults to `inbox`.", "schema": { "type": "string", "description": "The view. Defaults to `inbox`.", "enum": [ "inbox", "missions", "waiting", "sent", "done", "spam", "trials", "all" ] } }, { "name": "box", "in": "query", "required": false, "description": "Only conversations on this channel id (`GET /inbox/channels`).", "schema": { "type": "string", "description": "Only conversations on this channel id (`GET /inbox/channels`)." } }, { "name": "label", "in": "query", "required": false, "description": "Only conversations filed under this label key (`GET /inbox/categories`).", "schema": { "type": "string", "description": "Only conversations filed under this label key (`GET /inbox/categories`)." } }, { "name": "agent", "in": "query", "required": false, "description": "Only conversations of this AI collaborator (its id).", "schema": { "type": "string", "description": "Only conversations of this AI collaborator (its id)." } }, { "name": "q", "in": "query", "required": false, "description": "Search in message text, contact name, phone or email, reference and subject.", "schema": { "type": "string", "description": "Search in message text, contact name, phone or email, reference and subject." } }, { "name": "externalId", "in": "query", "required": false, "description": "Only conversations linked to this record of your software (`link.externalId`), exact. Use `folder=all` to include closed ones.", "schema": { "type": "string", "description": "Only conversations linked to this record of your software (`link.externalId`), exact. Use `folder=all` to include closed ones." } }, { "name": "reference", "in": "query", "required": false, "description": "Only conversations whose reference or link label equals this, case-insensitive.", "schema": { "type": "string", "description": "Only conversations whose reference or link label equals this, case-insensitive." } }, { "name": "email", "in": "query", "required": false, "description": "Only conversations of the contact holding this email address, exact.", "schema": { "type": "string", "description": "Only conversations of the contact holding this email address, exact." } }, { "name": "phone", "in": "query", "required": false, "description": "Only conversations of the contact holding this phone number (any format; digits are compared).", "schema": { "type": "string", "description": "Only conversations of the contact holding this phone number (any format; digits are compared)." } }, { "name": "sandbox", "in": "query", "required": false, "description": "Trial conversations: leave them out, show only them, or show all.", "schema": { "type": "string", "description": "Trial conversations: leave them out, show only them, or show all.", "enum": [ "exclude", "only", "all" ] } } ] }, "post": { "tags": [ "Conversations" ], "summary": "Write first to someone who has not written yet", "description": "Opens a conversation and sends the first message. **On WhatsApp**, if that person already wrote in the past, their existing thread is reused — one thread per person and channel.\n\n**On email, each call opens a new thread** (a thread is a subject). To add to an existing thread, pass its id as `threadId` (find it with `GET /inbox/conversations?externalId=…&folder=all`) or use `POST /inbox/conversations/{id}/messages`.\n\n**On WhatsApp, only an approved template can be sent here.** The 24-hour service window is closed by definition when nobody has written to you. This is Meta's rule, not ours: free text would be rejected by the gateway after letting you believe it had been sent. Pass `templateId` and its `variables`.\n\nOn email, send `text` and `subject` instead — or `html` for a formatted body (bold, italics, lists, quotes, links; anything else is removed). Attachments: `attachments` lists files your software hosts (fetched by Coplace), and/or one file rides along when the call is `multipart/form-data`: the JSON body in a `payload` field and the file in `file` (4 MB at most).\n\nWith `queue: true` the call returns at once (HTTP 202) and the message leaves within a minute.\n\nRequires a key with the `agent` role or above.", "operationId": "postApiV1InboxConversations", "responses": { "200": { "description": "The message as stored, its delivery status, and the id of the conversation it belongs to.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The message, and its conversation.", "properties": { "message": { "$ref": "#/components/schemas/Message" }, "duplicate": { "type": "boolean", "description": "`true` when this `idempotencyKey` was already used: the message returned is the first one, nothing was sent again." }, "conversationId": { "type": "string", "description": "The conversation it belongs to — new or reused." } } } } } } } }, "401": { "description": "Missing, malformed or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the required role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`template_required` — WhatsApp: a first message must be an approved template.\n\n`consent_missing` — A marketing template to a contact who opted out.\n\n`idempotency_key_conflict` — Two calls with the same key crossed at the same instant; retry, the first message comes back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`file_too_large` — An attachment is over 4 MB, or they total over 10 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`file_type_refused` — That type of file is not accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`template_holes_unfilled` — A placeholder has no value; `data.issues` lists them.\n\n`template_buttons_invalid` — A button value is missing or does not match the template's buttons; the message says which.\n\n`not_email` — `html`, `cc`, `bcc`, `attachments` and `threadId` only exist on email.\n\n`invalid_recipient` — `to` is not a readable email address or an international number (WhatsApp), or an address in `cc` or `bcc` is unreadable, or there are more than 10.\n\n`invalid_attachment` — An attachment has no `url`, or there are more than 5.\n\n`attachment_unreachable` — An attachment address could not be read; `data.url` names it.\n\n`invalid_thread` — `threadId` is not a thread of this channel with this contact.\n\n`attachment_unsupported` — WhatsApp: a first message is a template, without attachment.\n\n`invalid_link` — `link` is not an object, or has no `externalId`.\n\n`idempotency_key_required` — The idempotency key is missing or outside 8-200 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 600 calls per minute per key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channelId": { "type": "string", "description": "Which number or mailbox to speak from. See `GET /inbox/channels`." }, "to": { "type": "string", "description": "Phone number in E.164 form, or an email address.", "example": "+33612345678" }, "idempotencyKey": { "type": "string", "description": "Your own key, 8 to 200 characters. Sending twice with the same key sends once and returns the first message (`duplicate: true`) — even if the body differs." }, "templateId": { "type": "string", "description": "WhatsApp: the approved template to send. This or `templateName` is required there." }, "templateName": { "type": "string", "description": "WhatsApp: the template, by its name at Meta, instead of `templateId`." }, "templateLanguage": { "type": "string", "description": "With `templateName`: its language code. Default `fr`.", "example": "fr" }, "variables": { "type": "object", "description": "WhatsApp: the values filling the template placeholders — by number for `{{1}}`, by name for `{{client_name}}`: `{ \"1\": \"Karim\" }` or `{ \"client_name\": \"Karim\" }`." }, "buttons": { "type": "array", "description": "WhatsApp: the values of the template's dynamic buttons: `{ index, type, … }` — `index` is the button's position in the template (from 0), `type` is `url` (with `text`, the link suffix filling `{{1}}`), `quick_reply` (with `payload`) or `copy_code` (with `code`, 15 characters at most). A link button with `{{1}}` and a copy-code button must be given." }, "text": { "type": "string", "description": "Email: the body, as plain text." }, "html": { "type": "string", "description": "Email: the body as HTML. From an API key, a full layout is kept — tables, inline styles, `https` images (no `