Skip to content
Shortcut: /, ⌘K or Ctrl+K

Calls

View as Markdown

The call record object

Attributes

  • callIdstringrequired

    Call identifier.

  • projectIdstring (uuid)requirednullable

    Original owning project, retained after number deletion. Null when the original owner is unknown; those records appear only in team-wide reads.

  • sessionIdstringrequired

    Session name of the number that placed or received the call.

  • directionstringrequired

    Specifies direction for this management call record.

    Allowed valuesinboundoutbound
  • upstreamstringrequired

    How the number connects to WhatsApp.

    Allowed valueslinked_devicecloud_api
  • outcomestringrequired

    How 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_progress
  • statestringrequired

    Call outcome. offered and accepted calls may still be live. rejected is an incoming call a participant declined. missed is an incoming call that rang without an answer. Both keep that state after the call ends. ended covers every other finished call: answered calls, outgoing calls, and incoming calls the service could not host. endReason gives the cause.

    Allowed valuesofferedacceptedrejectedmissedended
  • hasVideobooleanrequired

    Whether video.

  • peerRefstringrequirednullable

    Team-specific pseudonym of the other party: the same party has the same value across your team's calls. Null when unknown.

  • startedAtstring (date-time)required

    Timestamp for started at.

  • connectedAtstring (date-time)requirednullable

    Timestamp for connected at.

  • endedAtstring (date-time)requirednullable

    Timestamp for ended at.

  • durationSecondsintegerrequirednullablemin0

    Connected 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, rejected or lost_connection. other for an unrecognized reason; null until the call ends.

The call record object
{
  "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

  • callsEnabledbooleanrequired

    Whether 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.

  • conferenceModebooleanrequired

    Conference 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.

  • inboundRoutestringrequired

    Specifies inbound route for this management platform access call setting.

    Allowed valuesclientssip_trunk
  • sipTrunkIdstring (uuid)requirednullable

    The SIP trunk that receives incoming calls when inboundRoute is sip_trunk; otherwise null.

  • sipClaimbooleanrequired

    Whether an answer from the SIP trunk claims the call, which ends ringing on your other clients. Defaults to true.

  • hostCloudApiCallsbooleanrequired

    Whether 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 /calls endpoint and Polymorfa Calls does not host them. Sessions on a linked device ignore it.

  • simultaneousCallsbooleanrequired

    Whether 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)requirednullable

    Read-only. While simultaneousCalls is 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 while simultaneousCalls is 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.

  • revisionintegerrequiredmin0

    Increases on every change; 0 while the session uses the defaults. Send it as expectedRevision to refuse an update that would overwrite someone else's change.

  • updatedAtstring (date-time)requirednullable

    When the settings were last changed, or null when the session uses the defaults.

The call settings object
{
  "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

GET/messaging/{session}/callsMessaging APILinked Device API
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

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Query parameters

  • limitstring

    Specifies limit for this query parameter.

  • cursorstring

    Specifies cursor for this query parameter.

  • directionstring

    Specifies direction for this query parameter.

    Allowed valuesinboundoutbound
  • outcomestring

    Specifies outcome for this query parameter.

    Allowed valuesansweredmisseddeclinedfailedin_progress
  • sincestring

    Specifies since for this query parameter.

  • untilstring

    Specifies until for this query parameter.

Responses

  • 200One page of calls.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 14 child fields
    • nextCursorstringrequirednullable

      Specifies 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
GET /messaging/{session}/callscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/callsPlatform API
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

  • projectIdstring

    Project to read. Omit to total every project in the team.

  • sessionIdstringlength1–128

    Identifier of the connected Polymorfa session.

  • directionstring

    Specifies direction for this query parameter.

    Allowed valuesinboundoutbound
  • upstreamstring

    Specifies upstream for this query parameter.

    Allowed valueslinked_devicecloud_api
  • outcomestring

    Specifies outcome for this query parameter.

    Allowed valuesansweredmisseddeclinedfailedin_progress
  • sincestring (date-time)

    Specifies since for this query parameter.

  • untilstring (date-time)

    Specifies until for this query parameter.

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 25
  • cursorstringlength1–256

    Specifies cursor for this query parameter.

Responses

  • 200Success
    • dataarray of objectrequiredmax items100

      Structured data carried by this object.

      Show 14 child fields
    • pageobjectrequired

      Specifies 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.
GET /platform/callscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/messaging/{session}/call-permissions/{to}Messaging APIMeta Cloud API
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

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • tostringrequired

    Specifies to for this path parameter.

Responses

  • 200The call permission.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
GET /messaging/{session}/call-permissions/{to}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/call-permissions/<to>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/sessions/{session}/call-settingsPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

Path parameters

  • sessionstringrequiredlength1–128

    Identifier of the connected Polymorfa session.

Responses

  • 200Call settings. Sessions without saved settings return the defaults.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
GET /platform/sessions/{session}/call-settingscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/sessions/<session>/call-settings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/call-retentionPlatform API
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.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
GET /platform/call-retentioncURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/call-retention" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "policy": "short",
    "retentionDays": 1,
    "appliesTo": [
      "string"
    ],
    "revision": 0,
    "updatedAt": "2026-09-22T12:00:00Z"
  }
}

Get call stats

GET/platform/calls/statsPlatform API
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

  • projectIdstring

    Project to read. Omit to total every project in the team.

  • sessionIdstringlength1–128

    Identifier of the connected Polymorfa session.

  • directionstring

    Specifies direction for this query parameter.

    Allowed valuesinboundoutbound
  • upstreamstring

    Specifies upstream for this query parameter.

    Allowed valueslinked_devicecloud_api
  • outcomestring

    Specifies outcome for this query parameter.

    Allowed valuesansweredmisseddeclinedfailedin_progress
  • sincestring (date-time)

    Specifies since for this query parameter.

  • untilstring (date-time)

    Specifies until for this query parameter.

  • groupBystring

    Specifies group by for this query parameter.

    Allowed valuesdayhoursessionoutcome
    Default "day"
  • timezonestringmax length64

    Specifies timezone for this query parameter.

    Default "UTC"

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
GET /platform/calls/statscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/calls/stats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

POST/messaging/voip/calls/checkMessaging API
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–128

    The session (number) that would place the call.

  • tostringrequiredlength1–64

    User ID or phone number in E.164 format.

Responses

  • 200Check result.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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.
POST /messaging/voip/calls/checkcURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "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

PUT/platform/sessions/{session}/call-settingsPlatform API
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–128

    Identifier of the connected Polymorfa session.

Body

  • callsEnabledboolean

    Set to false to refuse new and incoming calls on the session; true allows them again.

  • conferenceModeboolean

    Set 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.

  • inboundRoutestring

    Specifies inbound route for this management platform access update call settings request.

    Allowed valuesclientssip_trunk
  • sipTrunkIdstring (uuid)nullable

    The SIP trunk for sip_trunk: a trunk in the session's project whose direction is outbound or both. Required when switching the route to sip_trunk; omit it to keep the stored trunk. With clients send null or omit it: a trunk ID is refused, and clients clears the stored trunk.

  • sipClaimboolean

    Whether an answer from the SIP trunk claims the call.

  • hostCloudApiCallsboolean

    Set 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.

  • simultaneousCallsboolean

    Set 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 original acknowledgeRisk: true alias; 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.

  • termsLocalestring

    Language of the feature terms accepted inline. Defaults to English; use the locale returned with the terms.

    Allowed valuesenpt-BR
  • acceptTermsstringlength1–100

    The 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.

  • acknowledgeRiskboolean

    Confirms 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.

  • expectedRevisionintegermin0

    Apply the update only if the settings still have this revision (0 for a session using the defaults). Otherwise the update fails with 409 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.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
PUT /platform/sessions/{session}/call-settingscURL
Not available with the Test key. Use a team key or project token.
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
}'
Response
{
  "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

PUT/platform/call-retentionPlatform API
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

  • policystringrequired

    Specifies policy for this management platform access update call retention request.

    Allowed valuesshortstandardextendedcompliancecustom
  • retentionDaysintegerrange1–2555

    Required when policy is custom: a whole number of days from 1 to 2555. With a named policy, omit it or send that policy's period.

  • expectedRevisionintegermin0

    Apply the update only if the setting still has this revision (0 for a team using the default). Otherwise the update fails with 409 state_conflict.

Responses

  • 200Call data retention saved.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
PUT /platform/call-retentioncURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "success": true,
  "data": {
    "policy": "short",
    "retentionDays": 1,
    "appliesTo": [
      "string"
    ],
    "revision": 0,
    "updatedAt": "2026-09-22T12:00:00Z"
  }
}

Place outbound call

POST/messaging/voip/callsMessaging API
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 length1

    Identifier 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.

  • videoboolean

    Whether video.

  • exclusiveboolean

    Claim 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
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
POST /messaging/voip/callscURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "success": true,
  "data": {
    "callId": "string",
    "session": "string",
    "video": true
  }
}

Answer or join call

POST/messaging/voip/calls/{id}/acceptMessaging API
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 length1

    Identifier for this resource.

Body

  • videoboolean

    Whether video.

  • exclusiveboolean

    Claim the call. Other participants then receive 409 call_claimed for 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
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
POST /messaging/voip/calls/{id}/acceptcURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "success": true,
  "data": {
    "answered": true,
    "answeredBy": "client:agent-7",
    "exclusive": true
  }
}

Decline ringing call

POST/messaging/voip/calls/{id}/rejectMessaging API
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 length1

    Identifier 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
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-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
POST /messaging/voip/calls/{id}/rejectcURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "success": true
}

Leave call connection

POST/messaging/voip/calls/{id}/leaveMessaging API
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 length1

    Identifier 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
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-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
POST /messaging/voip/calls/{id}/leavecURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "success": true
}

Control call waiting room

POST/messaging/voip/calls/{id}/waiting-roomMessaging API
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 length1

    Identifier 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.

  • controlobjectrequired

    Specifies control for this native voip waiting room control request.

    One of
    • typestringrequired

      Type discriminator for this object.

      Allowed valueswaiting_room_control
    • requestIdstringrequiredpattern^[A-Za-z0-9_-]{8,64}$

      Client-chosen identifier of one media connection. Reusing it replaces that connection.

    • operationstringrequired

      Specifies operation for this one of.

      Allowed valuestoggle
    • enabledbooleanrequired

      Whether this feature is enabled.

Responses

  • 200Correlated provider outcome; inspect data.ok and data.code
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
POST /messaging/voip/calls/{id}/waiting-roomcURL
Not available with the Test key. Use a team key or project token.
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
  }
}'
Response
{
  "success": true,
  "data": {
    "type": "waiting_room_result",
    "requestId": "conn_0123456789",
    "ok": true
  }
}

Invite call participant

POST/messaging/voip/calls/{id}/participantsMessaging API
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 length1

    Identifier 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
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
POST /messaging/voip/calls/{id}/participantscURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "success": true,
  "data": {
    "id": "739182640518203",
    "audioMuted": true,
    "video": true,
    "state": "invited"
  }
}

Report call diagnostics

POST/messaging/voip/calls/{id}/reportsMessaging API
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 length1

    Identifier for this resource.

Body

One of
  • kindstringrequired

    Kind discriminator for this object.

    Allowed valuesquality
  • 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.

  • clientobject

    Specifies client for this native voip call quality report.

    Show 3 child fields
  • qualityobjectrequiredmin properties1

    Specifies quality for this native voip call quality report.

    Show 8 child fields

Responses

  • 202Report accepted
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-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
POST /messaging/voip/calls/{id}/reportscURL
Not available with the Test key. Use a team key or project token.
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
  }
}'
Response
{
  "success": true
}

End call

DELETE/messaging/voip/calls/{id}Messaging API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Ends the call and closes every connection. Repeating the request succeeds.

Path parameters

  • idstringrequiredmin length1

    Identifier for this resource.

Responses

  • 200Call ended
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-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
DELETE /messaging/voip/calls/{id}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/messaging/voip/calls/<id>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true
}

Reject call

POST/messaging/{session}/calls/{callId}/rejectMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
chats:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • callIdstringrequiredlength1–128

    Identifier of the WhatsApp call.

Body

  • fromstringrequiredpattern^[1-9][0-9]{0,18}$

    ID of the incoming caller

Responses

  • 200Call rejected
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-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
POST /messaging/{session}/calls/{callId}/rejectcURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "success": true
}

Export call records

GET/platform/calls/exportPlatform API
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–128

    Session name of one number.

  • directionstring

    Specifies direction for this query parameter.

    Allowed valuesinboundoutbound
  • upstreamstring

    How the number connects to WhatsApp.

    Allowed valueslinked_devicecloud_api
  • outcomestring

    How 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_progress
  • sincestring (date-time)

    Include calls that started at or after this time.

  • untilstring (date-time)

    Include calls that started before this time.

  • formatstring

    Specifies format for this query parameter.

    Allowed valuescsvndjson
    Default "csv"
  • limitintegerrange1–1000

    Records per page, up to 1,000.

    Default 1000
  • cursorstringlength1–256

    The Polymorfa-Next-Cursor value from the previous page. Send the same filters.

Responses

  • 200One page of call detail records.

    Content typetext/csvapplication/x-ndjson

    Show 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
GET /platform/calls/exportcURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/calls/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response

Content type text/csv, application/x-ndjson

No example for this content type