Theme
Sending conversation metadata
Some of what you know about a conversation never appears in the conversation itself: the booking it was about, the queue the call waited in, how long the customer was on hold. This endpoint lets the system that holds that data send it to Zefi, keyed by the conversation's id, so it shows up on the conversation and can be used to filter and score it.
POST https://public.eu.zefi.ai/v1/conversation-metadataIt is a batch endpoint: one request carries up to 64 KB of JSON (and at most 300 rows), and a daily feed is usually around ten requests. Split your batches by size, not only by row count. See Limits.
Before you start
Agree the fields
Your workspace accepts only the fields on its list. The Zefi team sets the list for you, once you have agreed it together, and a change applies from the next request you send. Each field has:
| Field name | Exactly as it appears in attributes, for example call_queue. Letters, digits and underscores. |
| Type | Text code (a short value from a fixed set, never free text), Number, True / false or Timestamp (RFC 3339 with a timezone). |
| Role | Attribute, or one of the identifiers you may send: Customer ID, Booking ID, Call ID, Chat ID, Chat URL or Agent ID. Identifiers are text codes. |
| Combine legs | How the values of several rows for one conversation become one: First leg, Last leg, Sum (numbers only) or List (every leg's value). See Legs. |
Never add a direct identifier, such as a name, email address, phone number, postal address, username or employee number. Fields named like one are refused.
Anything else you send is dropped before it is stored, and the response lists the names it dropped. This is on purpose: a column added to your export upstream, such as an email address, never reaches Zefi just because it was in the file.
A key can be given the conversation_metadata:write permission before the list is set, but until the list has fields, every attribute you send is dropped.
Create a key
Keys are created in the platform, by someone with access to the workspace the data belongs to:
- Open Settings → API Keys in that workspace.
- Create a key named after the system that will send the data, for example "Data warehouse – call metadata".
- Grant only
conversation_metadata:write. A feed that only sends data needs nothing else. - Copy the secret. It is shown once: Zefi stores a hash, not the key.
Put the key in the sending system's secret store, never in a script, a repository or a message. If it leaks, Replace it in the same screen. See Authentication for replacing, revoking and expiry.
Sending rows
bash
curl -X POST "https://public.eu.zefi.ai/v1/conversation-metadata" \
-H "Authorization: Bearer $ZEFI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"rows": [
{
"conversation_id": "c-123",
"leg_id": "1",
"attributes": {
"call_queue": "flights_it",
"on_hold_duration": 30,
"agent_id": "agent_017",
"outcome": "transferred"
}
},
{
"conversation_id": "c-123",
"leg_id": "2",
"attributes": {
"call_queue": "refunds_it",
"on_hold_duration": 45,
"agent_id": "agent_042",
"outcome": "refund_issued"
}
}
]
}'| Field | Required | |
|---|---|---|
conversation_id | Yes | Your id for the conversation, exactly as it appears in the conversation data you send Zefi through your other channel (for calls, the call id on the recording). 1–128 characters. |
leg_id | No | Tells apart several rows for the same conversation, such as the legs of a transferred call. 1–64 characters. |
attributes | Yes | The agreed fields, as a flat object. Values are strings, numbers, booleans or null. |
Send timestamps as RFC 3339 in UTC, like everywhere else in the API (see Requests and responses). null means "no value" and is the same as leaving the field out.
Two kinds of unknown field
Unknown fields are handled differently depending on where they are:
- Inside
attributes, a field that isn't agreed for your workspace is dropped. The row is still accepted, and the field's name is listed indropped_fields. - Anywhere else (at the top level or on a row), an unknown field is a typo, not data. The request or row is rejected as a validation failure, as in the rest of the API.
The response
202 when every row was accepted:
json
{
"request_id": "0f4c9a2e-1d3b-4a7c-9f21-8b6d5e4c3a10",
"accepted": 300,
"rejected": 0,
"dropped_fields": [],
"errors": []
}207 when at least one row was rejected. The other rows are accepted:
json
{
"request_id": "6b8e2f1a-4c3d-4e7f-9a21-0d5c6b7e8f90",
"accepted": 298,
"rejected": 2,
"dropped_fields": ["email_address"],
"errors": [
{
"index": 17,
"conversation_id": "c-140",
"leg_id": "2",
"error": {
"type": "about:blank",
"title": "Validation failed",
"code": "VALIDATION_FAILED",
"detail": "attributes.on_hold_duration: expected a number"
}
},
{
"index": 212,
"conversation_id": null,
"leg_id": null,
"error": {
"type": "about:blank",
"title": "Validation failed",
"code": "VALIDATION_FAILED",
"detail": "conversation_id: Invalid input: expected string, received undefined"
}
}
]
}207 is not a failure
Most of the batch was accepted. Read errors to fix the rows that weren't and send only those again. Resending the whole batch is also safe (see below).
request_ididentifies this request. Keep it with your job's log: it's what we ask for if you need help with a delivery.dropped_fieldslists the attribute names not accepted for your workspace, once each, whichever rows carried them. Values are never echoed. If a name is there that you expected to be accepted, it isn't in the workspace's list yet.indexis the row's position in the request.
202 means the rows are stored. When they are used on your conversations is agreed with the Zefi team when the feed is set up.
Legs
Rows that share a conversation_id are the legs of one conversation, for example one row per leg of a transferred call. Each field's Combine legs rule says how their values become one.
Legs are ordered by leg_id:
- An id that is a whole number sorts as a number, so
2comes before10. - Other ids sort as text, after the whole-number ones.
- A row without a
leg_idcomes first.
"First leg", "last leg" and the order of a "list" all follow this order, so give legs ids that sort in the order they happened.
Retrying is safe
A row is identified by conversation_id plus leg_id. Sending the same pair again replaces the earlier row instead of adding a second one.
So a whole batch can be resent after a timeout, a 5xx or a 429 without creating duplicates. That's the opposite of creating survey links, which is not idempotent.
Limits
| Request body | Up to 64 KB. A larger body is refused before it reaches the API (see below). |
| Rows per request | 1–300. More returns 413 BATCH_TOO_LARGE. |
conversation_id | 1–128 characters |
leg_id | 1–64 characters |
| Attributes per row | Up to 100 |
| String values | Up to 1,000 characters |
| Number values | Between −9,007,199,254,740,991 and 9,007,199,254,740,991 (2^53 − 1). Non-zero values must be at least 1e-130 in size. Anything else rejects the row. |
| Rate limit | Each request is one write against your key's write budget, however many rows it carries |
Split by size
The body limit is usually the one you reach first. A row with a handful of short attributes is 200–300 bytes, so 64 KB holds around 200–300 rows; rows with long values fit fewer. Build each request by adding rows until the serialised JSON would pass 64 KB, then start the next one:
python
import json
LIMIT = 64 * 1024 - 512 # headroom for the {"rows": [...]} envelope
def chunks(rows):
batch, size = [], 0
for row in rows:
row_size = len(json.dumps(row).encode()) + 1
if batch and (size + row_size > LIMIT or len(batch) == 300):
yield batch
batch, size = [], 0
batch.append(row)
size += row_size
if batch:
yield batchA few thousand rows a day is around ten requests, far inside the default budget. Send them one after another rather than all at once.
An oversized body gets an HTML 403
A body over 64 KB is stopped at the edge, before authentication and before the API runs. You get 403 with an HTML page that says "The request could not be satisfied", not a JSON problem document, and nothing is stored. If you see that page, the request was too large: split it and send the parts.
Errors
| Status | code | Means | Retry? |
|---|---|---|---|
400 | VALIDATION_FAILED | rows is missing, empty or not an array, or the body has an unknown top-level field | No, fix the request |
401 | — | No bearer token | No |
403 | — | The key is malformed, unknown, revoked or expired | No |
403 (HTML page) | — | The body is over 64 KB and was refused at the edge | No, split the batch |
403 | INSUFFICIENT_SCOPE | The key lacks conversation_metadata:write | No |
413 | BATCH_TOO_LARGE | More than 300 rows | No, split the batch |
429 | RATE_LIMIT_EXCEEDED | Write budget spent for this minute | Yes, after Retry-After |
5xx | — | Our fault | Yes, with backoff |
Problems with a single row, such as a missing conversation_id, a value of the wrong type or an unknown field on the row, don't fail the request. They come back in errors with a 207.
