Menu
POST calls/transcript-link/ Service tier

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)

KeyRequiredDefault
agent_nameoptional or conditionalnone
agent_public_idoptional or conditionalnone
call_idoptional or conditionalnone
channel_public_idoptional or conditionalnone
ended_atoptional or conditionalnone
started_atoptional or conditionalnone
transcript_urloptional or conditionalnone

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

200 data 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).

Errors

StatusCode
400invalid_datetime
400invalid_url
400missing_field
403not_a_member
404channel_not_found

Example

curl -X POST "https://comms.mattering.io/api/internal/v1/calls/transcript-link/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_name": "...",
  "agent_public_id": "...",
  "call_id": "...",
  "channel_public_id": "...",
  "ended_at": "...",
  "started_at": "...",
  "transcript_url": "..."
}'

Source: CommsCore/api.py (api.push_transcript_link)

POST calls/{channel_public_id}/guest-link/ Service tier

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

NameType
channel_public_idstr

Body keys (JSON)

KeyRequiredDefault
agent_public_idoptional or conditionalnone

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

200 data and meta envelope

{
  "data": {
    "id": "...",
    "url": "...",
    "label": "...",
    "expires_at": "2026-01-01T00:00:00Z",
    "auto_admit": "..."
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_expires_hours
400missing_field
401unauthorized
403not_a_member
403unknown_agent
404channel_not_found
423channel_archived

Example

curl -X POST "https://comms.mattering.io/api/internal/v1/calls/CHANNEL_PUBLIC_ID/guest-link/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_public_id": "..."
}'

Source: CommsCore/api.py (api.agent_call_guest_link)

POST calls/{channel_public_id}/presence/ Service tier

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

NameType
channel_public_idstr

Body keys (JSON)

KeyRequiredDefault
agent_public_idoptional or conditionalnone

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

200 data and meta envelope

{
  "data": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400missing_field
401unauthorized
403not_a_member
403unknown_agent
404channel_not_found

Example

curl -X POST "https://comms.mattering.io/api/internal/v1/calls/CHANNEL_PUBLIC_ID/presence/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_public_id": "..."
}'

Source: CommsCore/api.py (api.agent_call_presence)

POST calls/{channel_public_id}/recording/ Service tier

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

NameType
channel_public_idstr

Body keys (JSON)

KeyRequiredDefault
agent_public_idoptional or conditionalnone

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

200 data and meta envelope

{
  "data": {
    "recording": {
      "on": false
    },
    "already": true
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400missing_field
401unauthorized
403not_a_member
403unknown_agent
404channel_not_found
409no_live_call
503recording_unavailable

Example

curl -X POST "https://comms.mattering.io/api/internal/v1/calls/CHANNEL_PUBLIC_ID/recording/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_public_id": "..."
}'

Source: CommsCore/api.py (api.agent_call_recording)

POST calls/{channel_public_id}/screen-share/ Service tier

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

NameType
channel_public_idstr

Body keys (JSON)

KeyRequiredDefault
agent_nameoptional or conditionalnone
agent_public_idoptional or conditionalnone
share_idoptional or conditionalnone
sharingoptional or conditionalnone
stateoptional or conditionalnone

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

200 data 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).

Errors

StatusCode
400missing_field
401unauthorized
404channel_not_found

Example

curl -X POST "https://comms.mattering.io/api/internal/v1/calls/CHANNEL_PUBLIC_ID/screen-share/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_name": "...",
  "agent_public_id": "...",
  "share_id": "...",
  "sharing": "...",
  "state": "..."
}'

Source: CommsCore/api.py (api.screen_share_push)

All Comms resources
Start Free Explore our Products