Calls
One call detail record.
The call record object
Attributes
callIdstringrequiredCall identifier.
projectIdstring (uuid)requirednullableOriginal owning project, retained after number deletion. Null when the original owner is unknown; those records appear only in team-wide reads.
sessionIdstringrequiredSession name of the number that placed or received the call.
directionstringrequiredSpecifies direction for this management call record.
Allowed valuesinboundoutboundupstreamstringrequiredHow the number connects to WhatsApp.
Allowed valueslinked_devicecloud_apioutcomestringrequiredHow the call went.
answered: media connected, including answered calls still in progress.declined: declined by a participant or the other party, or the line was busy.missed: nobody answered before ringing stopped or the caller hung up.failed: ended before it connected for any other reason, such as a connection or capacity failure.in_progress: still ringing.Allowed valuesansweredmisseddeclinedfailedin_progressstatestringrequiredCall outcome.
offeredandacceptedcalls may still be live.rejectedis an incoming call a participant declined.missedis an incoming call that rang without an answer. Both keep that state after the call ends.endedcovers every other finished call: answered calls, outgoing calls, and incoming calls the service could not host.endReasongives the cause.Allowed valuesofferedacceptedrejectedmissedendedhasVideobooleanrequiredWhether video.
peerRefstringrequirednullableTeam-specific pseudonym of the other party: the same party has the same value across your team's calls. Null when unknown.
startedAtstring (date-time)requiredTimestamp for started at.
connectedAtstring (date-time)requirednullableTimestamp for connected at.
endedAtstring (date-time)requirednullableTimestamp for ended at.
durationSecondsintegerrequirednullablemin0Connected seconds; 0 for a call that never connected and null until the call ends.
endReasonstringrequirednullablepattern^[a-z][a-z0-9_]{0,63}$Why the call ended, such as
user_hangup,ring_timeout,rejectedorlost_connection.otherfor an unrecognized reason; null until the call ends.
{
"callId": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"sessionId": "string",
"direction": "inbound",
"upstream": "linked_device",
"outcome": "answered",
"state": "offered",
"hasVideo": true,
"peerRef": "string",
"startedAt": "2026-09-22T12:00:00Z",
"connectedAt": "2026-09-22T12:00:00Z",
"endedAt": "2026-09-22T12:00:00Z",
"durationSeconds": 0,
"endReason": "user_hangup"
}The call settings object
Attributes
callsEnabledbooleanrequiredWhether the session can place, answer and receive calls. When false, placing, answering, joining and attaching media fail with
403 calls_disabled, incoming calls are declined, and SIP trunks cannot place calls through the session. Calls in progress continue, and the participant that answered or placed one can reconnect to it. Defaults to true.conferenceModebooleanrequiredConference mode. When true, every participant you connect to a call (including SIP trunk callers) hears the WhatsApp party and every other participant you connected. When false, each of them hears only the WhatsApp party. The WhatsApp party always hears all of your participants, and no participant hears their own audio. Defaults to true.
inboundRoutestringrequiredSpecifies inbound route for this management platform access call setting.
Allowed valuesclientssip_trunksipTrunkIdstring (uuid)requirednullableThe SIP trunk that receives incoming calls when
inboundRouteissip_trunk; otherwise null.sipClaimbooleanrequiredWhether an answer from the SIP trunk claims the call, which ends ringing on your other clients. Defaults to true.
hostCloudApiCallsbooleanrequiredWhether Polymorfa Calls answers the session's incoming calls when the session uses the Cloud API. When false (the default), your app answers them through the Graph API
/callsendpoint and Polymorfa Calls does not host them. Sessions on a linked device ignore it.simultaneousCallsbooleanrequiredWhether this Number may hold more than one call at a time, with no limit. Linked-device sessions only; Cloud API sessions ignore it. WhatsApp's own apps never hold two calls at once, so this behavior is unusual for WhatsApp, and it voids Ban Credit: a ban whose 30-day window overlaps any period this setting was on is not covered. Defaults to false.
simultaneousCallsCoverageExcludedUntilstring (date-time)requirednullableRead-only. While
simultaneousCallsis false, when Ban Credit stops excluding this Number because of an earlier period with it on: 30 days after the latest period ended. A ban is excluded when the setting was on at any time in the 30 days before it, so until this time, a new ban is not covered; from this time on, that period no longer excludes a ban. Null whilesimultaneousCallsis true, because the exclusion has no end yet, and null when no period ended in the last 30 days. Null does not mean the Number is covered: the other Ban Credit conditions still apply.revisionintegerrequiredmin0Increases on every change; 0 while the session uses the defaults. Send it as
expectedRevisionto refuse an update that would overwrite someone else's change.updatedAtstring (date-time)requirednullableWhen the settings were last changed, or null when the session uses the defaults.
{
"callsEnabled": true,
"conferenceMode": true,
"inboundRoute": "clients",
"sipTrunkId": "00000000-0000-4000-8000-000000000000",
"sipClaim": true,
"hostCloudApiCalls": true,
"simultaneousCalls": true,
"simultaneousCallsCoverageExcludedUntil": "2026-09-22T12:00:00Z",
"revision": 0,
"updatedAt": "2026-09-22T12:00:00Z"
}List session calls
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Calls on this number, newest first, with the other party's identity. Records are stored and served in the number's data region. Client tokens need the read_calls action.
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
Query parameters
limitstringSpecifies limit for this query parameter.
cursorstringSpecifies cursor for this query parameter.
directionstringSpecifies direction for this query parameter.
Allowed valuesinboundoutboundoutcomestringSpecifies outcome for this query parameter.
Allowed valuesansweredmisseddeclinedfailedin_progresssincestringSpecifies since for this query parameter.
untilstringSpecifies until for this query parameter.
Responses
200One page of calls.
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataarray of objectrequiredStructured data carried by this object.
Show 14 child fields
nextCursorstringrequirednullableSpecifies next cursor for this native list session calls response.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl "https://api.polymorfa.com/messaging/<session>/calls" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": [
{
"callId": "string",
"projectId": "string",
"sessionId": "string",
"direction": "inbound",
"upstream": "linked_device",
"outcome": "answered",
"state": "offered",
"hasVideo": true,
"peer": {
"id": "string",
"phoneNumber": "string",
"username": "string"
},
"startedAt": "string",
"connectedAt": "string",
"endedAt": "string",
"durationSeconds": 0,
"endReason": "string"
}
],
"nextCursor": "string"
}List call records
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Lists call detail records, newest first. Filter by project, number, direction, connection, outcome and start time. The other party appears only as peerRef, a team-specific pseudonym; phone numbers are never returned. Pass page.nextCursor as cursor with the same filters to read the next page.
Requires sessions:read. Project tokens only access resources in their own project.
Query parameters
projectIdstringProject to read. Omit to total every project in the team.
sessionIdstringlength1–128Identifier of the connected Polymorfa session.
directionstringSpecifies direction for this query parameter.
Allowed valuesinboundoutboundupstreamstringSpecifies upstream for this query parameter.
Allowed valueslinked_devicecloud_apioutcomestringSpecifies outcome for this query parameter.
Allowed valuesansweredmisseddeclinedfailedin_progresssincestring (date-time)Specifies since for this query parameter.
untilstring (date-time)Specifies until for this query parameter.
limitintegerrange1–100Specifies limit for this query parameter.
Default25cursorstringlength1–256Specifies cursor for this query parameter.
Responses
200Success
dataarray of objectrequiredmax items100Structured data carried by this object.
Show 14 child fields
pageobjectrequiredSpecifies page for this schema.
Show 2 child fields
Show 3 headers
400A path, query, or request-body value did not pass validation.
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
curl "https://api.polymorfa.com/platform/calls" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"callId": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"sessionId": "string",
"direction": "inbound",
"upstream": "linked_device",
"outcome": "answered",
"state": "offered",
"hasVideo": true,
"peerRef": "string",
"startedAt": "2026-09-22T12:00:00Z",
"connectedAt": "2026-09-22T12:00:00Z",
"endedAt": "2026-09-22T12:00:00Z",
"durationSeconds": 0,
"endReason": "user_hangup"
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}Get call permission
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns whether the person has allowed this number to call them. On Cloud API numbers WhatsApp is asked on every request and the answer includes its limits on permission requests and calls. Linked-device numbers return 409 unsupported_for_connection.
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
tostringrequiredSpecifies to for this path parameter.
Responses
200The call permission.
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 8 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409`unsupported_for_connection`: the number is not a Cloud API number.
500Internal server error
curl "https://api.polymorfa.com/messaging/<session>/call-permissions/<to>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": {
"conversation": {
"id": "739182640518203"
},
"status": "none",
"expiresAt": "2026-09-22T12:00:00Z",
"source": "user_action",
"updatedAt": "2026-09-22T12:00:00Z",
"checkedAt": "2026-09-22T12:00:00Z",
"fresh": true,
"actions": {
"requestPermission": {
"allowed": true,
"limits": [
{
"period": "string",
"maxAllowed": 0,
"used": 0,
"resetsAt": "2026-09-22T12:00:00Z"
}
]
},
"startCall": {
"allowed": true,
"limits": [
{
"period": "string",
"maxAllowed": 0,
"used": 0,
"resetsAt": "2026-09-22T12:00:00Z"
}
]
}
}
}
}Get call settings
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Path parameters
sessionstringrequiredlength1–128Identifier of the connected Polymorfa session.
Responses
200Call settings. Sessions without saved settings return the defaults.
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 10 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl "https://api.polymorfa.com/platform/sessions/<session>/call-settings" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": {
"callsEnabled": true,
"conferenceMode": true,
"inboundRoute": "clients",
"sipTrunkId": "00000000-0000-4000-8000-000000000000",
"sipClaim": true,
"hostCloudApiCalls": true,
"simultaneousCalls": true,
"simultaneousCallsCoverageExcludedUntil": "2026-09-22T12:00:00Z",
"revision": 0,
"updatedAt": "2026-09-22T12:00:00Z"
}
}Get call retention
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns how long Polymorfa keeps your team's call data. Teams without a saved setting return the default.
Responses
200The team's call data retention.
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 5 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl "https://api.polymorfa.com/platform/call-retention" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": {
"policy": "short",
"retentionDays": 1,
"appliesTo": [
"string"
],
"revision": 0,
"updatedAt": "2026-09-22T12:00:00Z"
}
}Get call stats
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns call volume, outcomes, answer rate and connected duration for a time range, grouped by day, hour, number or outcome, with an hour-of-week heatmap. Filters match the call records endpoints. Without since and until the range is the last 7 days. Day and hour groups use the requested timezone and include empty buckets.
Requires sessions:read. Project tokens only access resources in their own project.
Query parameters
projectIdstringProject to read. Omit to total every project in the team.
sessionIdstringlength1–128Identifier of the connected Polymorfa session.
directionstringSpecifies direction for this query parameter.
Allowed valuesinboundoutboundupstreamstringSpecifies upstream for this query parameter.
Allowed valueslinked_devicecloud_apioutcomestringSpecifies outcome for this query parameter.
Allowed valuesansweredmisseddeclinedfailedin_progresssincestring (date-time)Specifies since for this query parameter.
untilstring (date-time)Specifies until for this query parameter.
groupBystringSpecifies group by for this query parameter.
Allowed valuesdayhoursessionoutcomeDefault"day"timezonestringmax length64Specifies timezone for this query parameter.
Default"UTC"
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 8 child fields
Show 3 headers
400A path, query, or request-body value did not pass validation.
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
503`service_unavailable`: the statistics took too long to compute. Narrow the range or filters and retry.
curl "https://api.polymorfa.com/platform/calls/stats" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"since": "2026-09-22T12:00:00Z",
"until": "2026-09-22T12:00:00Z",
"timezone": "string",
"groupBy": "day",
"totals": {
"calls": 0,
"answered": 0,
"missed": 0,
"declined": 0,
"failed": 0,
"inProgress": 0,
"answerRate": 0,
"totalDurationSeconds": 0,
"averageDurationSeconds": 0
},
"groups": [
{
"key": "string",
"start": "2026-09-22T12:00:00Z",
"calls": 0,
"answered": 0,
"missed": 0,
"declined": 0,
"failed": 0,
"inProgress": 0,
"answerRate": 0,
"totalDurationSeconds": 0,
"averageDurationSeconds": 0
}
],
"groupsTruncated": true,
"heatmap": [
{
"dayOfWeek": 1,
"hour": 0,
"calls": 0,
"answered": 0
}
]
}
}Check call
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Runs the checks a call placement runs, without calling: the number's calling switch, the team's do-not-call list and blocked country codes, and on Cloud API numbers the person's call permission and WhatsApp's call limits. If WhatsApp's permission status is unavailable and no other refusal is known, returns 503 service_unavailable. Server credentials only.
Body
sessionstringrequiredlength1–128The session (number) that would place the call.
tostringrequiredlength1–64User ID or phone number in E.164 format.
Responses
200Check result.
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 3 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
503`service_unavailable`: required call-check state is unavailable; retry later.
curl -X POST "https://api.polymorfa.com/messaging/voip/calls/check" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"session": "string",
"to": "string"
}'{
"success": true,
"data": {
"allowed": true,
"refusal": "calls_disabled",
"permission": {
"status": "none",
"expiresAt": "2026-09-22T12:00:00Z",
"source": "user_action",
"updatedAt": "2026-09-22T12:00:00Z",
"checkedAt": "2026-09-22T12:00:00Z",
"fresh": true,
"actions": {
"requestPermission": {
"allowed": true,
"limits": [
{
"period": null,
"maxAllowed": null,
"used": null,
"resetsAt": null
}
]
},
"startCall": {
"allowed": true,
"limits": [
{
"period": null,
"maxAllowed": null,
"used": null,
"resetsAt": null
}
]
}
}
}
}
}Update call settings
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Changes the settings you send; omitted settings keep their current values. Send expectedRevision to refuse the update when someone else changed the settings after you read them.
Path parameters
sessionstringrequiredlength1–128Identifier of the connected Polymorfa session.
Body
callsEnabledbooleanSet to false to refuse new and incoming calls on the session; true allows them again.
conferenceModebooleanSet to true so that the participants you connect to a call hear each other as well as the WhatsApp party, or false so that each hears only the WhatsApp party.
inboundRoutestringSpecifies inbound route for this management platform access update call settings request.
Allowed valuesclientssip_trunksipTrunkIdstring (uuid)nullableThe SIP trunk for
sip_trunk: a trunk in the session's project whose direction isoutboundorboth. Required when switching the route tosip_trunk; omit it to keep the stored trunk. Withclientssendnullor omit it: a trunk ID is refused, andclientsclears the stored trunk.sipClaimbooleanWhether an answer from the SIP trunk claims the call.
hostCloudApiCallsbooleanSet to true to have Polymorfa Calls answer the session's Cloud API calls instead of your Graph API integration. Applies to calls that arrive after the change.
simultaneousCallsbooleanSet to true to let this Number hold more than one call at a time, with no limit. Turning it on requires a team API key and risk acknowledgement, using
acceptTerms, a recorded current acceptance, or the originalacknowledgeRisk: truealias; it voids Ban Credit for any ban whose 30-day window overlaps a period it was on. Set to false to return to one call at a time. Applies to calls that start after the change.termsLocalestringLanguage of the feature terms accepted inline. Defaults to English; use the locale returned with the terms.
Allowed valuesenpt-BRacceptTermsstringlength1–100The published simultaneous-call terms version to accept for this Number. The original acknowledgeRisk: true remains an alias for simultaneous-calls-v1. Unpublished terms add no requirement.
acknowledgeRiskbooleanConfirms the original simultaneous-calls-v1 risk acknowledgement. A later published version requires acceptTerms or a recorded current acceptance. Confirms the unusual-behavior risk and loss of Ban Credit for this Number.
expectedRevisionintegermin0Apply the update only if the settings still have this
revision(0 for a session using the defaults). Otherwise the update fails with409 state_conflict.
Responses
200Call settings saved. Audio settings apply to a call the next time a participant answers or connects to it, including calls in progress. Routing settings apply to calls that arrive after the change.
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 10 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409`state_conflict`: the settings changed after `expectedRevision`. `terms_acceptance_required`: accept the current published simultaneous-call terms.
500Internal server error
curl -X PUT "https://api.polymorfa.com/platform/sessions/<session>/call-settings" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"callsEnabled": true,
"conferenceMode": true,
"inboundRoute": "clients",
"sipTrunkId": "00000000-0000-4000-8000-000000000000",
"sipClaim": true,
"hostCloudApiCalls": true,
"simultaneousCalls": true,
"termsLocale": "en",
"acceptTerms": "string",
"acknowledgeRisk": true,
"expectedRevision": 0
}'{
"success": true,
"data": {
"callsEnabled": true,
"conferenceMode": true,
"inboundRoute": "clients",
"sipTrunkId": "00000000-0000-4000-8000-000000000000",
"sipClaim": true,
"hostCloudApiCalls": true,
"simultaneousCalls": true,
"simultaneousCallsCoverageExcludedUntil": "2026-09-22T12:00:00Z",
"revision": 0,
"updatedAt": "2026-09-22T12:00:00Z"
}
}Update call retention
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Records how long Polymorfa keeps your team's call data. Requires a team API key. Deletion of call data older than the period starts on a date Polymorfa announces in the changelog; until then, saving a period deletes nothing. Once deletion runs, a shorter period also applies to call data already stored, and deleted data cannot be recovered. Send expectedRevision to refuse the update when someone else changed the setting after you read it.
Body
policystringrequiredSpecifies policy for this management platform access update call retention request.
Allowed valuesshortstandardextendedcompliancecustomretentionDaysintegerrange1–2555Required when
policyiscustom: a whole number of days from 1 to 2555. With a named policy, omit it or send that policy's period.expectedRevisionintegermin0Apply the update only if the setting still has this
revision(0 for a team using the default). Otherwise the update fails with409 state_conflict.
Responses
200Call data retention saved.
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 5 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409`state_conflict`: the setting changed after `expectedRevision`.
500Internal server error
curl -X PUT "https://api.polymorfa.com/platform/call-retention" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"policy": "short"
}'{
"success": true,
"data": {
"policy": "short",
"retentionDays": 1,
"appliesTo": [
"string"
],
"revision": 0,
"updatedAt": "2026-09-22T12:00:00Z"
}
}Place outbound call
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Originates a WhatsApp call to to, an ad-hoc group call to participants (2 to 31 distinct E.164 phone numbers or public user IDs), or every remote member of groupId (a public group ID). Group rosters must contain 2 to 31 remote members; a membership change during placement refuses the call. Provide exactly one destination form. Group calls require a Linked Device number and check every recipient against the team policy and number restrictions before dialing. The call is owned by the placing participant and rings on the callee's device: call.accepted follows when they pick up and call.ended when either side hangs up. Carry its audio and video with a Polymorfa Calls SDK. exclusive: true claims the call for the placing participant. Client tokens place from their bound session; server credentials must name one. Outbound starts share a rate limit per team and source session across server credentials and client tokens; client-token rules also apply.
Body
Provide exactly one of: to, participants or groupId
sessionstringmin length1Identifier of the connected Polymorfa session.
tostringpattern^(?:\+[1-9]\d{1,14}|[1-9][0-9]{0,18})$Specifies to for this native voip place call request.
groupIdstringpattern^[1-9][0-9]{0,18}$Identifier for the group.
participantsarray of stringitems2–31unique itemsitem pattern^(?:\+[1-9]\d{1,14}|[1-9][0-9]{0,18})$Participants associated with the group or conversation.
videobooleanWhether video.
exclusivebooleanClaim the call for the placing participant.
participantstringpattern^[A-Za-z0-9._:@-]{1,128}$Server credentials only: the participant acting in the call. Defaults to
default. Client tokens act as their own participant and must omit this field.
Responses
201Call placed and ringing
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 3 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
402`gate_limit_reached` when an enforced usage limit refuses placement; `entitlement_required` when the account lacks a required capability. The outbound monthly gate remains in record mode until placement reservations are available.
403`call_permission_required` when the recipient has not granted this business permission to call them, `number_restricted` when WhatsApp restricts the number to calling people it has already chatted with and the callee is not one of them (`Retry-After` gives the seconds until the restriction ends, when known), or the credential is not permitted
404Resource not found
409`unsupported_for_connection` when the session's connection cannot place this call (Cloud API calls are audio only), or `state_conflict` when the named session cannot place an outbound call yet
410Call ended — the pod that owned its media is gone (pod_lost)
429Outbound call rate exceeded for this team and source session, which every credential shares, or a client token's own request rate (`rateLimit`) was exceeded.
500Internal server error
501Outbound calls are not available on this deployment
502`upstream_failure` when the Cloud API refused or failed the call action
503Call unavailable — the owning pod is at capacity or draining, call authority cannot be verified, or usage limits could not be checked
curl -X POST "https://api.polymorfa.com/messaging/voip/calls" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"session": "support",
"to": "+15550100",
"groupId": "string",
"participants": [
"string"
],
"video": true,
"exclusive": true,
"participant": "agent-7"
}'{
"success": true,
"data": {
"callId": "string",
"session": "string",
"video": true
}
}Answer or join call
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
The first accept answers a ringing call. exclusive: true claims it: other participants then receive 409 call_claimed for accept and media, and their open connections close. Without a claim, later accepts join the answered call. Retrying with the same participant returns the same result. An exclusive request from another participant on a shared call is refused with 409 call_claimed.
Path parameters
idstringrequiredmin length1Identifier for this resource.
Body
videobooleanWhether video.
exclusivebooleanClaim the call. Other participants then receive
409 call_claimedfor accept and media, and their open connections close.participantstringpattern^[A-Za-z0-9._:@-]{1,128}$Server credentials only: the participant acting in the call. Defaults to
default. Client tokens act as their own participant and must omit this field.
Responses
200Call answered or joined
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 3 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409`call_claimed` when another participant claimed the call, or `state_conflict` when the call is not ready
410Call ended — the pod that owned its media is gone (pod_lost)
500Internal server error
503Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified
curl -X POST "https://api.polymorfa.com/messaging/voip/calls/<id>/accept" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"video": true,
"exclusive": true,
"participant": "agent-7"
}'{
"success": true,
"data": {
"answered": true,
"answeredBy": "client:agent-7",
"exclusive": true
}
}Decline ringing call
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Declines a ringing call and releases it. Returns 409 call_not_ringing when the call is not ringing.
Path parameters
idstringrequiredmin length1Identifier for this resource.
Body
participantstringpattern^[A-Za-z0-9._:@-]{1,128}$Server credentials only: the participant acting in the call. Defaults to
default. Client tokens act as their own participant and must omit this field.
Responses
202Call declined
successbooleanrequiredWhether the request succeeded.
messagestringHuman-readable message associated with this result.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409`call_not_ringing` when the call was already answered, declined, or ended
410Call ended — the pod that owned its media is gone (pod_lost)
500Internal server error
503Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified
curl -X POST "https://api.polymorfa.com/messaging/voip/calls/<id>/reject" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"participant": "agent-7"
}'{
"success": true
}Leave call connection
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Disconnects the named connection. The call and the participant's other connections continue. Use DELETE /voip/calls/{id} to end the call for everyone.
Path parameters
idstringrequiredmin length1Identifier for this resource.
Body
connectionIdstringrequiredpattern^[A-Za-z0-9_-]{8,64}$Client-chosen identifier of one media connection. Reusing it replaces that connection.
participantstringpattern^[A-Za-z0-9._:@-]{1,128}$Server credentials only: the participant acting in the call. Defaults to
default. Client tokens act as their own participant and must omit this field.
Responses
202Connection closed
successbooleanrequiredWhether the request succeeded.
messagestringHuman-readable message associated with this result.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409Call not ready — no media session on the owning pod yet
410Call ended — the pod that owned its media is gone (pod_lost)
500Internal server error
503Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified
curl -X POST "https://api.polymorfa.com/messaging/voip/calls/<id>/leave" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "conn_0123456789"
}'{
"success": true
}Control call waiting room
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Reauthorizes the credential and current Number/project on each request. Requires the answering participant's attached connection and current provider administrator authority. A result with ok=false reports a refusal or unknown outcome. Never replay uncertain moderation.
Path parameters
idstringrequiredmin length1Identifier for this resource.
Body
connectionIdstringrequiredpattern^[A-Za-z0-9_-]{8,64}$Client-chosen identifier of one media connection. Reusing it replaces that connection.
participantstringpattern^[A-Za-z0-9._:@-]{1,128}$Server credentials only: the participant acting in the call, which must own the connection. Defaults to
default. Client tokens act as their own participant and must omit this field.controlobjectrequiredSpecifies control for this native voip waiting room control request.
One oftypestringrequiredType discriminator for this object.
Allowed valueswaiting_room_controlrequestIdstringrequiredpattern^[A-Za-z0-9_-]{8,64}$Client-chosen identifier of one media connection. Reusing it replaces that connection.
operationstringrequiredSpecifies operation for this one of.
Allowed valuestoggleenabledbooleanrequiredWhether this feature is enabled.
Responses
200Correlated provider outcome; inspect data.ok and data.code
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 4 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409The call is not ready (`state_conflict`), or the calling backend does not support this action (`unsupported_for_connection`).
410Call ended — the pod that owned its media is gone (pod_lost)
500Internal server error
503Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified
curl -X POST "https://api.polymorfa.com/messaging/voip/calls/<id>/waiting-room" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "conn_0123456789",
"control": {
"type": "waiting_room_control",
"requestId": "conn_0123456789",
"operation": "toggle",
"enabled": true
}
}'{
"success": true,
"data": {
"type": "waiting_room_result",
"requestId": "conn_0123456789",
"ok": true
}
}Invite call participant
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Rings to (an E.164 phone number or a user ID) into the call, turning a 1:1 call into a group call. The invitee enters the roster as invited; roster changes reach media sockets as participant_joined / participant_state / participant_left frames. 409 until the call has a live leg.
Path parameters
idstringrequiredmin length1Identifier for this resource.
Body
tostringrequiredpattern^(?:\+[1-9]\d{1,14}|[1-9][0-9]{0,18})$Specifies to for this native voip add participant request.
Responses
201Participant invited
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 8 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403`number_restricted` when WhatsApp restricts the number to calling people it has already chatted with and the invitee is not one of them (`Retry-After` gives the seconds until the restriction ends, when known), or the credential is not permitted
404Resource not found
409`unsupported_for_connection` when the session connects through the Cloud API, which has no group calls, or `state_conflict` when the call has no live leg yet
410Call ended — the pod that owned its media is gone (pod_lost)
429Request rate exceeded for this client token (its `rateLimit` rule)
500Internal server error
503Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified
curl -X POST "https://api.polymorfa.com/messaging/voip/calls/<id>/participants" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"to": "+15550100"
}'{
"success": true,
"data": {
"id": "739182640518203",
"audioMuted": true,
"video": true,
"state": "invited"
}
}Report call diagnostics
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Records quality figures or an error that your app measured for one of its connections. The Console shows the latest quality report and the reported errors of each connection on the call. Reports are optional and are accepted while the call is live and for 10 minutes after it ends. Each connection can send one quality report every 5 seconds and 20 error reports per minute. At most 200 reports are kept per call: at that limit a quality report replaces the same connection's oldest quality report. A quality report from a connection with no stored quality report, and every error report, is accepted but not stored.
Path parameters
idstringrequiredmin length1Identifier for this resource.
Body
kindstringrequiredKind discriminator for this object.
Allowed valuesqualityconnectionIdstringrequiredpattern^[A-Za-z0-9_-]{8,64}$Client-chosen identifier of one media connection. Reusing it replaces that connection.
participantstringpattern^[A-Za-z0-9._:@-]{1,128}$Server credentials only: the participant acting in the call. Defaults to
default. Client tokens act as their own participant and must omit this field.clientobjectSpecifies client for this native voip call quality report.
Show 3 child fields
qualityobjectrequiredmin properties1Specifies quality for this native voip call quality report.
Show 8 child fields
Responses
202Report accepted
successbooleanrequiredWhether the request succeeded.
messagestringHuman-readable message associated with this result.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409`state_conflict` when the call is not live, ended more than 10 minutes ago, or is outside the credential's boundary
410Call ended — the pod that owned its media is gone (pod_lost)
429The connection exceeded its report limit: one quality report every 5 seconds or 20 error reports per minute
500Internal server error
503Call authority or report storage is unavailable
curl -X POST "https://api.polymorfa.com/messaging/voip/calls/<id>/reports" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"kind": "quality",
"connectionId": "conn_0123456789",
"quality": {
"rttMs": 84,
"jitterMs": 6,
"packetsLost": 12,
"packetsReceived": 4810,
"audioCodec": "audio/opus",
"videoCodec": "video/VP8",
"candidateType": "host",
"reconnects": 0
}
}'{
"success": true
}End call
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Ends the call and closes every connection. Repeating the request succeeds.
Path parameters
idstringrequiredmin length1Identifier for this resource.
Responses
200Call ended
successbooleanrequiredWhether the request succeeded.
messagestringHuman-readable message associated with this result.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409Call not ready — no media session on the owning pod yet
410Call ended — the pod that owned its media is gone (pod_lost)
500Internal server error
503Call unavailable — the owning pod is at capacity or draining, or call authority cannot be verified
curl -X DELETE "https://api.polymorfa.com/messaging/voip/calls/<id>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true
}Reject call
- Base URL
https://api.polymorfa.com- Required permission
chats:manage
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
callIdstringrequiredlength1–128Identifier of the WhatsApp call.
Body
fromstringrequiredpattern^[1-9][0-9]{0,18}$ID of the incoming caller
Responses
200Call rejected
successbooleanrequiredWhether the request succeeded.
messagestringHuman-readable message associated with this result.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl -X POST "https://api.polymorfa.com/messaging/<session>/calls/<callId>/reject" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"from": "string"
}'{
"success": true
}Export call records
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns up to 1,000 call detail records per request as CSV or newline-delimited JSON, newest first, with the same fields and filters as List call records. The other party appears only as peerRef, a team-specific pseudonym. Each CSV page starts with a header row. When more records match, the Polymorfa-Next-Cursor response header carries the cursor for the next page; it is absent on the last page.
Query parameters
projectIdstring (uuid)Project to read. Omit to total every project in the team. Project tokens always read their own project.
sessionIdstringlength1–128Session name of one number.
directionstringSpecifies direction for this query parameter.
Allowed valuesinboundoutboundupstreamstringHow the number connects to WhatsApp.
Allowed valueslinked_devicecloud_apioutcomestringHow the call went.
answered: media connected, including answered calls still in progress.declined: declined by a participant or the other party, or the line was busy.missed: nobody answered before ringing stopped or the caller hung up.failed: ended before it connected for any other reason.in_progress: still ringing.Allowed valuesansweredmisseddeclinedfailedin_progresssincestring (date-time)Include calls that started at or after this time.
untilstring (date-time)Include calls that started before this time.
formatstringSpecifies format for this query parameter.
Allowed valuescsvndjsonDefault"csv"limitintegerrange1–1000Records per page, up to 1,000.
Default1000cursorstringlength1–256The
Polymorfa-Next-Cursorvalue from the previous page. Send the same filters.
Responses
200One page of call detail records.
Content type
text/csvapplication/x-ndjsonShow 4 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl "https://api.polymorfa.com/platform/calls/export" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"Content type text/csv, application/x-ndjson
No example for this content type