Matter pushes an agent-call transcript link onto the channel's call card (agent-calls spec, "Transcript link on the call card", hook 1).
INTERNAL TIER ONLY (mounted solely under ``/api/internal/v1/calls/ transcript-link/``: see MatteringComms/urls.py): Matter is the only caller, acting AS the agent (``X-Internal-User-Email: agent+<id>@agents.mattering.io``: the resolve_identity JIT path accepts the synthetic identity, and the agent was in the call so it already holds a ChannelMembership).
Body (JSON): channel_public_id, started_at/ended_at (ISO datetimes: the AGENT's window), agent_public_id, agent_name, call_id, transcript_url (must pass ^https?://).
Gates, fail-closed: channel resolved in the acting org (404 channel_not_found: no cross-org existence oracle); the acting user must hold a ChannelMembership in it (403 not_a_member); scheme-checked URL (400 invalid_url); parseable datetimes (400 invalid_datetime).
Matching: the newest kind='call' record in THAT channel whose meta window overlaps [started_at, ended_at] with +-60 s slack (bounded scan: see call_transcripts.find_matching_call_record). On match the entry is merged into meta['transcripts'] (DEDUPED on (call_id, agent_public_id): a re-push is idempotent), saved with update_fields, and the re-serialized message is broadcast best-effort as message.update (the unfurl pattern) so open clients gain the affordance live. Responds {data: {attached: true}}.
No matching record (the record is written when the LAST human leaves, so the push may beat it): a PendingTranscriptLink row is persisted for consumers._persist_call_record to attach, and the response is {data: {attached: false}}. Matter logs-and-ignores non-2xx.
URL
Service tierhttps://comms.mattering.io/api/internal/v1/calls/transcript-link/
Body keys (JSON)
Key
Required
Default
agent_name
optional or conditional
none
agent_public_id
optional or conditional
none
call_id
optional or conditional
none
channel_public_id
optional or conditional
none
ended_at
optional or conditional
none
started_at
optional or conditional
none
transcript_url
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200data and meta envelope
{
"data": {
"attached": false
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
POST /api/internal/v1/calls/<channel>/guest-link/ {agent_public_id, label?, expires_hours?}
An agent mints a guest call link for its channel (the same invite a member creates), attributed to the agent. Returns the shareable URL; the raw token is shown once and never stored.
This read is not paginated. It returns at most 32 rows and does not report a total, so a result of exactly 32 may be truncated.
URL
Service tierhttps://comms.mattering.io/api/internal/v1/calls/{channel_public_id}/guest-link/
Path parameters
Name
Type
channel_public_id
str
Body keys (JSON)
Key
Required
Default
agent_public_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
POST /api/internal/v1/calls/<channel>/presence/ {agent_public_id}
{live, in_call} for the agent in this channel's Call, read from THIS process's registries. Matter calls it when the voice runtime reports "already in the call" so a stranded runtime session (e.g. its socket left on a draining instance after a deploy) is detected and replaced rather than trusted.
This read is not paginated. It returns at most 32 rows and does not report a total, so a result of exactly 32 may be truncated.
URL
Service tierhttps://comms.mattering.io/api/internal/v1/calls/{channel_public_id}/presence/
Path parameters
Name
Type
channel_public_id
str
Body keys (JSON)
Key
Required
Default
agent_public_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200data and meta envelope
{
"data": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
POST /api/internal/v1/calls/<channel>/recording/ {on, agent_public_id}
An agent starts or stops recording the live call in its channel. The whole call is told ({t:'recording'} on the call group), so humans see the pill and their clients begin/stop keeping slices, exactly as when a member presses Record. 409 when no call is running.
This read is not paginated. It returns at most 32 rows and does not report a total, so a result of exactly 32 may be truncated.
URL
Service tierhttps://comms.mattering.io/api/internal/v1/calls/{channel_public_id}/recording/
Path parameters
Name
Type
channel_public_id
str
Body keys (JSON)
Key
Required
Default
agent_public_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Agents pushes "an agent's browser share started / stopped" for a call.
INTERNAL TIER ONLY: POST /api/internal/v1/calls/<channel>/screen-share/ with X-Internal-Secret (the guard middleware gates the prefix; the secret is re-checked here in constant time, fail-closed when unset). Body: {share_id, agent_public_id, agent_name, state, sharing, ...}.
The channel must exist (404 otherwise); unknown agents are logged and ignored (200 {ok: true, ignored: true}). The event is broadcast on the call's realtime group as {t:'agent.screen'} so open call pages add or drop the tile at once. The list Agents serves is the truth; this is the nudge (the page reconciles against the list on join and every 15 s). Never blocks on anything slow.
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
Service tierhttps://comms.mattering.io/api/internal/v1/calls/{channel_public_id}/screen-share/
Path parameters
Name
Type
channel_public_id
str
Body keys (JSON)
Key
Required
Default
agent_name
optional or conditional
none
agent_public_id
optional or conditional
none
share_id
optional or conditional
none
sharing
optional or conditional
none
state
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200data and meta envelope
{
"data": {
"ok": true,
"ignored": true
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
We use strictly necessary cookies to run this site. With your permission we also use analytics cookies
(Google Analytics and our own visit tracking) to see which pages work. Read the
Cookie notice.