Customers & conversations
In the API, a customer is one agent in your account: one chat widget with its own configuration, conversations and billing. Conversation data is reached through its customer, so most paths start with /customers/{id}.
Request examples omit the Authorization: Bearer gtmc_... header for brevity; every request needs it. See authentication.
Customers
The customer object
{
"id": 42,
"orgId": "org_2h9x4kQ",
"name": "Acme website",
"widgetKey": "wk_8f3a2c19d7e44b0c9a61f25d3b7e8c04",
"conversionType": "booked_meeting",
"conversionLabel": "Book a demo",
"bookingUrl": "https://acme.com/demo",
"personaPrompt": null,
"allowedScope": null,
"refusalPolicy": null,
"brandColor": "#2563eb",
"escalationThreshold": 0.7,
"motion": "demo_booking",
"vertical": "saas",
"provisioningStatus": "ready",
"active": true,
"createdAt": "2026-09-02T14:00:00.000Z",
"updatedAt": "2026-10-01T10:30:00.000Z",
"delivrPixelId": null,
"leadEmailRecipients": ["sales@acme.com"],
"leadEmailTranscript": true,
"visitorTranscriptEnabled": false,
"serviceEmailRecipients": []
}
| Field | Type | Notes |
|---|---|---|
id | integer | Customer id |
orgId | string | Your account's organization id |
name | string | |
widgetKey | string | Public key the chat widget uses |
conversionType | string | One of booked_meeting, qualified_lead, sale, resolved_ticket, custom, captured_contact, qualified_meeting |
conversionLabel | string or null | |
bookingUrl | string or null | Your own booking link |
personaPrompt | string or null | |
allowedScope | string or null | |
refusalPolicy | string or null | |
brandColor | string | Hex colour, #rrggbb |
escalationThreshold | number | 0 to 1 |
motion | string or null | One of demo_booking, quote, self_serve, purchase, qualification, support |
vertical | string or null | |
provisioningStatus | string | pending, ready or failed |
active | boolean | false once deleted |
createdAt, updatedAt | date-time | |
delivrPixelId | string or null | |
leadEmailRecipients | array of strings | Who receives lead emails. Read only in the API |
leadEmailTranscript | boolean | Whether lead emails include the transcript. Read only in the API |
visitorTranscriptEnabled | boolean | Whether visitors can request a copy of their chat. Read only in the API |
serviceEmailRecipients | array of strings | Read only in the API |
The four read-only fields are set in the dashboard.
List customers
GET /api/v1/customers?limit=20 HTTP/1.1
Host: app.gtmclarity.ai
Returns active customers, newest first, as { "data": [customer, ...], "has_more": false }. Parameters: limit (1 to 100, default 20), starting_after (a customer id). Needs an agency-scoped key. Responses: 200, 400, 401, 403, 429.
Create a customer
POST /api/v1/customers HTTP/1.1
Host: app.gtmclarity.ai
Content-Type: application/json
Idempotency-Key: create-acme-website
{
"name": "Acme website",
"conversionType": "booked_meeting",
"conversionLabel": "Book a demo",
"brandColor": "#2563eb",
"motion": "demo_booking",
"vertical": "saas"
}
| Field | Type | Notes |
|---|---|---|
name | string | Required, 1 to 200 characters |
personaPrompt | string | |
conversionType | string | See the customer object |
conversionLabel | string | |
allowedScope | string | |
refusalPolicy | string | |
brandColor | string | #rrggbb |
motion | string | See the customer object |
vertical | string | Non-empty |
Other fields are rejected. Returns 201 with the customer. Needs a write key with agency scope; Idempotency-Key is optional (see idempotency). A suspended account gets 403 with code account_stopped. Responses: 201, 400, 401, 403, 409, 429.
Retrieve a customer
GET /api/v1/customers/42 HTTP/1.1
Host: app.gtmclarity.ai
Returns the customer, including a deleted one (active: false). Responses: 200, 401, 403, 404, 429.
Update a customer
PATCH /api/v1/customers/42 HTTP/1.1
Host: app.gtmclarity.ai
Content-Type: application/json
{
"bookingUrl": "https://acme.com/meet",
"escalationThreshold": 0.6
}
Send at least one of: name, personaPrompt, conversionType, conversionLabel, bookingUrl, allowedScope, refusalPolicy, brandColor, escalationThreshold (0 to 1), motion, vertical. Every field except name, conversionType, brandColor and escalationThreshold also accepts null. Other fields, including the four read-only ones, are rejected. Returns the updated customer. A deleted customer returns 400 with code customer_deactivated. Needs a write key. Responses: 200, 400, 401, 403, 404, 429.
Delete a customer
DELETE /api/v1/customers/42 HTTP/1.1
Host: app.gtmclarity.ai
{
"deleted": true,
"id": 42
}
Deactivates the customer: it stops appearing in List customers, stays readable by id with active: false, and can no longer be updated. There is no endpoint to reactivate it. A suspended account gets 403 with code account_stopped. Needs an admin key. Responses: 200, 401, 403, 404, 429.
Widget config
The widget-facing subset of a customer.
GET /api/v1/customers/42/widget-config HTTP/1.1
Host: app.gtmclarity.ai
{
"personaPrompt": null,
"conversionType": "booked_meeting",
"conversionLabel": "Book a demo",
"allowedScope": null,
"refusalPolicy": null,
"brandColor": "#2563eb",
"escalationThreshold": 0.7,
"motion": "demo_booking",
"vertical": "saas",
"widgetKey": "wk_8f3a2c19d7e44b0c9a61f25d3b7e8c04",
"delivrPixelId": null
}
PATCH /api/v1/customers/{id}/widget-config takes the same fields as Update a customer except bookingUrl, and returns the widget config. It needs a write key and rejects a deleted customer with 400 (customer_deactivated).
Responses: GET 200, 401, 403, 404, 429. PATCH 200, 400, 401, 403, 404, 429.
Conversations
Conversation endpoints return 404 until the customer's provisioningStatus is ready.
The conversation object
{
"id": 118,
"status": "closed",
"converted": true,
"convertedAt": "2026-10-14T15:20:11.000Z",
"identityResolved": true,
"visitorId": "6f9d2c1e-8a3b-4f70-9c55-2d41e0b7a9c3",
"startedAt": "2026-10-14T15:04:05.000Z",
"endedAt": "2026-10-14T15:31:40.000Z",
"lead": {
"name": "Ada Lovelace",
"firstName": null,
"lastName": null,
"email": "ada@example.com",
"phone": "+61400000000",
"company": null,
"callbackRequested": true,
"preferredContactTime": "after 5pm",
"chatStartedOn": "https://example.com/sell"
}
}
| Field | Type | Notes |
|---|---|---|
id | integer | Conversation id, unique within the customer |
status | string | open, ai_active, human_active, closed or converted |
converted | boolean | |
convertedAt | date-time or null | |
identityResolved | boolean | |
visitorId | string or null | |
startedAt | date-time | |
endedAt | date-time or null | |
lead | object or null | The contact details captured on the chat: what the visitor typed or an operator entered. null once the chat is erased. Fields as in the captured lead |
List conversations
GET /api/v1/customers/42/conversations?converted=true&started_after=2026-10-01T00:00:00Z HTTP/1.1
Host: app.gtmclarity.ai
| Parameter | Type | Notes |
|---|---|---|
limit | integer | 1 to 100, default 20 |
starting_after | integer | A conversation id |
status | string | One of the status values above |
converted | true or false | |
started_after | date-time | Conversations started after this time |
Returns { "data": [conversation, ...], "has_more": false }, newest first. Responses: 200, 400, 401, 403, 404, 429.
Retrieve a conversation
GET /api/v1/customers/42/conversations/118 HTTP/1.1
Host: app.gtmclarity.ai
Returns the conversation object. Responses: 200, 401, 403, 404, 429.
List messages
GET /api/v1/customers/42/conversations/118/messages?limit=50 HTTP/1.1
Host: app.gtmclarity.ai
{
"data": [
{
"id": 901,
"role": "user",
"content": "Do you integrate with Salesforce?",
"createdAt": "2026-10-14T15:04:05.000Z"
},
{
"id": 902,
"role": "assistant",
"content": "Yes. Leads and transcripts sync to Salesforce.",
"createdAt": "2026-10-14T15:04:07.000Z"
}
],
"has_more": false
}
role is user (the visitor), assistant (the AI), agent (a human operator) or system.
| Parameter | Type | Notes |
|---|---|---|
limit | integer | 1 to 100, default 50 |
starting_after | integer | A message id, default 0 |
include_system | true or false | System messages are left out unless true |
Messages are returned oldest first. Responses: 200, 400, 401, 403, 404, 429.