Save Conversation
POST/v1/open-api/call-history
Submit a conversation held in an external system — a phone call, an offline meeting or an online meeting. The record appears in UYSOT as a call note on the lead, in the conversation journal and in the telephony statistics.
The whole payload is validated synchronously, so a malformed request never reaches
the queue and the caller gets 400 immediately. Persisting is asynchronous: the
response carries a requestId, poll GET /v1/open-api/request/{requestId} for the
outcome. A SUCCESS status of this call means "the message was accepted", not yet
"written to the journal" — the write itself is what the requestId reports on.
leadId is required: this flow does not look a lead up by phone number and never
creates one, so the caller must say which lead the conversation belongs to. An unknown
leadId or employeeId is therefore reported as a FAILED request status, not as a
404 here.
Idempotent by uuid. Re-sending the same uuid does not create a second record.
The platform stores it prefixed with oapi-, and that prefixed value is what
POST /v1/open-api/call-history/filter returns — keep your own uuid as the key on
your side.
Derived fields are computed for you and must not be sent: the end timestamp
(startedAt + durationSec), the hangup cause (from answered), the direction
bookkeeping (from direction), and the provider, which is always OPEN_API.
Requires grant PERMISSION_OPEN_API_CALL:SAVE.
Request
Responses
- 200
- 400
- 401
- 403
- 429
Conversation accepted and enqueued. Poll requestId for the result.
Validation error (400). Field-level failures are listed in errors[] and error is
null; a malformed / unparsable JSON body is the inverse — error.messageCode is
3705 and errors[] is empty.
Invalid, revoked or expired token (401) — also returned when the connection was
revoked or the company is blocked.
Produced by the authentication filter, so the body is a reduced envelope: no
error, no requestId, and errors is null rather than []. Every cause yields the
same fixed English message.
The token lacks the required permission:scope grant (403).
Rate limit of 60 requests/minute exceeded (429). Like 401, this comes from the
authentication filter: reduced envelope, fixed English message, no error object and no
Retry-After header.