Phone Call List

Tags: communication, telephony, voice

Voice call history and management

Resources

Request and response models used by the endpoints on this page.

AgentMemoryConfig

Field	Type	Required	Description
enabled	Boolean		Default: False
episodic	Boolean		Default: False
preferences	Boolean		Default: True
semantic	Boolean		Default: True
summaries	Boolean		Default: True

Example:

{
  "enabled": false,
  "preferences": true,
  "semantic": true,
  "summaries": true,
  "episodic": false
}

BaseAssistantResponse

Field	Type	Required	Description
chatModel	String
chatModelConfig	Dict[str, Any]
codeInterpreterEnabled	Boolean		Default: False
description	String
id	Integer
identity	String
memoryConfig	AgentMemoryConfig | null
name	String	✓
realtimeModel	String
realtimeModelConfig	Dict[str, Any]
tools	Array		Default: []
webBrowserEnabled	Boolean		Default: False

Example:

{
  "name": "string",
  "tools": [],
  "codeInterpreterEnabled": false,
  "webBrowserEnabled": false
}

MemberExperimentGroupSummary

Field	Type	Required	Description
groupId	Integer	✓
groupName	String	✓
groupSlug	String	✓
isControl	Boolean	✓

Example:

{
  "groupId": 0,
  "groupName": "string",
  "groupSlug": "string",
  "isControl": false
}

MemberLabelResponse

Field	Type	Required	Description
color	String	✓
description	String	✓
id	Integer	✓
name	String	✓
slug	String	✓
uuid	String	✓

Example:

{
  "id": 0,
  "uuid": "string",
  "name": "string",
  "slug": "string",
  "color": "string",
  "description": "string"
}

PaginatedResponse[PhoneCallResponse]

Field	Type	Required	Description
items	Array<PhoneCallResponse>	✓
page	Integer	✓
pageSize	Integer	✓
total	Integer	✓
totalPages	Integer	✓

Example:

{
  "items": [],
  "total": 0,
  "page": 0,
  "pageSize": 0,
  "totalPages": 0
}

PhoneCallResponse

Field	Type	Required	Description
agent	BaseAssistantResponse | null
carrierStatus	String		Twilio CallStatus / DialCallStatus terminal value (GRA-6416): completed, busy, no-answer, failed, or canceled. Independent of product intent — a successful transfer is terminationReason=forward + carrierStatus=completed; a transfer whose destination was busy is forward + busy.
chatId	Integer
chatUuid	String		Uuid of the chat the call belongs to (chatId's public identifier). Null when the call has no chat.
createdAt	DateTime	✓
credits	Number
failureDetail	String		Transport / infra failure detail (GRA-6416): connection_reset (Twilio ErrorCode on completed call), stream_reset (media-stream WebSocket reset, e.g. Twilio 31921), never_connected (bridge-leg provisional), timeout, bridge_call_create_failed, bridge_call_create_missing_sid, fax_t30_failed, other closed fax_* receive codes, or error.
finishedAt	DateTime
id	Integer	✓
inbound	Boolean	✓
member	WorkspaceMemberResponse | null
phoneNumberId	Integer	✓
startedAt	DateTime
status	String	✓
terminationReason	String		Product / app outcome for how the call ended (GRA-6416). Preferred values: hangup (assistant ended), forward (call forwarded), handoff, completed (caller hung up / normal end), policy rejects (voice_disabled, anonymous_rejected, …), blocked_outbound_safety, strict_voice_blocked, voicemail, amd_unknown. Legacy rows may also hold carrier strings (busy, no-answer, …) or transport failures (connection_reset, stream_reset, never_connected); prefer carrierStatus / failureDetail when present. Null for in-progress/unknown calls.
twilioCallId	String	✓
uuid	String	✓	Public identifier of the call — the uuid the Activity Spine (organization webhooks v2) uses as the call subject.
workflowId	Integer		ID of the workflow associated with this call, resolved via the chat's assignment (PhoneCall.chat_id -> Chat.assignment_id -> Assignment.workflow_revision_id -> WorkflowRevision.workflow_id). Null for direct human-to-human calls with no chat, or chats with no assignment.

Example:

{
  "id": 0,
  "uuid": "string",
  "phoneNumberId": 0,
  "twilioCallId": "string",
  "status": "string",
  "createdAt": "2024-01-01T00:00:00Z",
  "inbound": false
}

SharedContactResponse

Field	Type	Required	Description
archived	Boolean		Default: False
field	Literal['phone', 'email']	✓
memberId	Integer	✓

Example:

{
  "field": "phone",
  "memberId": 0,
  "archived": false
}

WorkspaceMemberResponse

Field	Type	Required	Description
accountEnabled	Boolean
accountTosAccepted	Boolean	✓
accountUuid	String	✓
canLogin	Boolean		Default: True
createdAt	DateTime	✓
dateOfBirth	Date
description	String	✓
email	String	✓
emailVerified	Boolean		Default: False
experimentGroup	MemberExperimentGroupSummary | null
externalId	String	✓
homeFolderId	Integer
id	Integer	✓
isArchived	Boolean		Default: False
isImportProtected	Boolean		Default: False
isOrgOwner	Boolean
isSuperuser	Boolean
labels	Array<MemberLabelResponse>		Default: []
locale	String	✓
memberRoleId	Integer	✓
memberRoleName	String	✓
memberRoleSystemKey	String
memberType	String		Default: member
name	String	✓
notifyEmail	Boolean	✓
notifySms	Boolean	✓
notifyVoice	Boolean	✓
notifyWhatsapp	Boolean		Default: False
orgRole	String
phone	String	✓
phoneType	String	✓
phoneVerified	Boolean		Default: False
role	String	✓
sharedContactPlacements	Array<SharedContactResponse>		Default: []
timezone	String
title	String
tosAccepted	Boolean	✓
updatedAt	DateTime	✓
usagePaused	Boolean		Default: False
uuid	String	✓

Example:

{
  "id": 0,
  "uuid": "string",
  "role": "string",
  "tosAccepted": false,
  "accountTosAccepted": false,
  "accountUuid": "string",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "name": "string",
  "description": "string",
  "phone": "string",
  "phoneType": "string",
  "email": "string",
  "externalId": "string",
  "emailVerified": false,
  "phoneVerified": false,
  "notifySms": false,
  "notifyEmail": false,
  "notifyVoice": false,
  "notifyWhatsapp": false,
  "locale": "string",
  "memberRoleId": 0,
  "memberRoleName": "string",
  "labels": [],
  "memberType": "member",
  "isArchived": false,
  "isImportProtected": false,
  "usagePaused": false,
  "canLogin": true,
  "sharedContactPlacements": []
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/calls - List
• GET /api/v2/w/{workspace_uuid}/calls/by-uuid/{uuid} - By Uuid

List

GET /api/v2/w/{workspace_uuid}/calls

Description:

List phone calls in the workspace.

Optional filters: phoneNumberId (int PK), chatId, workflowId, callId, status, inbound, and date range (dateFrom / dateTo). Requires phones:read scope. callId is an equality predicate on the same audited, scope-gated listing; it intersects every other filter and returns an empty page when the target is unavailable.

Authorization: Requires phones:read scope

Parameters:

• page (Integer) — min: 1
• page_size (Integer) — min: 1, max: 100
• phoneNumberId (Integer)
• chatId (Integer)
• workflowId (Integer)
• callId (Integer)
• status (CallStatus)
• inbound (Boolean)
• dateFrom (datetime)
• dateTo (datetime)

Response: See PaginatedResponse[PhoneCallResponse]

---

By Uuid

GET /api/v2/w/{workspace_uuid}/calls/by-uuid/{uuid}

Description:

Get one phone call by uuid — the subject of call.completed / call.summary in organization webhooks v2.

Authorization is GET /chats/\{chat_id}/phone-calls's, applied to the call's own chat: chats:read, then get_chat_or_raise's chat access policy (get_readable_phone_call_by_uuid_or_404). A call the caller's chat access does not reach — and a call with no chat, which that policy cannot be applied to — is a 404 identical to a missing uuid, so the route is not an existence oracle. A uuid from another workspace cannot resolve; the session sees one workspace schema.

The response carries chatId and chatUuid so the caller can read the chat (and its summary) next. The path segment is \{uuid} so @phi_audit records the numeric call id via resource_id.

Authorization: Requires chats:read scope

Parameters:

• uuid (String)

Response: See PhoneCallResponse

---