Create engagement
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
The engagement type. Only CALL and MEETING are supported for creation via the public API.
Identifier for the external system that produced this recording (e.g. salesforce, custom-dialer). Stored as metadata for traceability but not part of the idempotency key — see external_id.
Unique identifier for this engagement in the external system. Used as the idempotency key scoped to the workspace (not per source_system). Submitting the same external_id again — even with a different source_system — returns the existing engagement instead of creating a duplicate. If you need per-source uniqueness, prefix the ID yourself (e.g. my-crm:12345).
Controls whether downstream automations (workflow triggers, post-meeting recap emails) fire for this engagement. Set to true to enable normal automation; set to false to suppress workflows (useful for historical imports). Transcription, summarization, and tagging always run regardless of this flag.
Publicly accessible HTTPS URL pointing to the audio or video recording. Required unless transcript_timeline is provided for a structured transcript-only import. The server fetches this URL during request processing, so it must be reachable at call time. Requirements: must use the https scheme (no http), must not resolve to private or internal IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x, 127.x.x.x, 169.254.x.x, or IPv6 link-local/loopback), and must serve an audio/* or video/* content type.
Controls whether the engagement is marked as private. When true, only participants and users with engagements:private:read scope can view the engagement. Defaults to the workspace’s configured privacy behavior if omitted.
Structured transcript timeline for transcript-only engagement imports. Use this when you already have diarized transcript turns and no recording media. Each entry references a declared speaker by speaker_index; entry and sentence time ranges must be non-negative, no longer than 7 days, and sentence windows must stay within their parent entry window.
Optional URL linking back to this engagement in the originating system (e.g. a dialer’s call detail page). Accepts https://, http://, and custom app deep-link schemes such as wavv://call/123. Dangerous schemes (javascript:, data:, vbscript:, blob:, file:) are rejected. The value is stored as-is and returned in API responses and webhook payloads.
Deprecated. Use structured transcript_timeline for transcript imports. If provided, stored alongside the media recording; the media will still be processed through the transcription pipeline. Limited to 900,000 characters and 950,000 bytes (UTF-8). Multi-byte content (e.g. CJK, emoji) may hit the byte limit before the character limit.
Response headers
Response
An engagement with the same external_id already exists in this workspace. The existing engagement is returned unchanged.
Structured transcript timeline returned by POST /v2/engagements. When no structured timeline exists yet, this is returned as an empty transcript timeline with no speakers or entries. For read-after-create retrieval, use GET /v2/engagements/{engagement_id}/transcript_timeline.
URL linking back to this engagement in the originating external system (e.g. a dialer’s call detail page). Accepts https://, http://, and custom app deep-link schemes such as wavv://call/123. Present only when the engagement was created with an external_url value.
Full text transcript of the engagement. Only included when expand contains transcript.
Temporary signed URL for downloading the engagement recording media. Only included when expand contains media_url. The URL expires after a short period.
Companies associated with this engagement. Only included when expand contains companies.
Contact participants associated with this engagement. Only included when expand contains contacts.
Workspace user who owns this engagement. Only included when expand contains owner.
Action items created from this engagement. Only included when expand contains action_items.
Signals (annotations) extracted from this engagement. Only included when expand contains signals.