Click-to-call

POST

api

integrations

custom

click-to-call

curl --request POST \
  --url https://api.ringee.io/api/integrations/custom/click-to-call \
  --header 'Content-Type: application/json' \
  --header 'X-Ringee-Api-Key: <api-key>' \
  --data '
{
  "contactExternalId": "ext_contact_42",
  "agentEmail": "rep@example.com"
}
'

{
  "contactId": "6b2f8f1e-6a2e-4f1c-9a3d-2d1b0c7e4a55",
  "agentUserId": "a91c4d77-1f0b-4a2e-8c3d-77b1e2f4a9c0",
  "toNumber": "+14155550123",
  "fromNumber": "+14155550100",
  "dialerUrl": "https://app.ringee.io/dashboard/dialer?session=eyJhbGciOi...&to=%2B14155550123&from=%2B14155550100",
  "sessionToken": "eyJhbGciOi...",
  "expiresAt": "2026-05-23T14:35:00.000Z"
}

{
  "statusCode": 400,
  "message": "Must provide either contactExternalId (linked to a contact) or phoneNumber",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Must provide either contactExternalId (linked to a contact) or phoneNumber",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Must provide either contactExternalId (linked to a contact) or phoneNumber",
  "error": "Bad Request"
}

Click-to-call exchanges a contact for a short-lived, signed dialer URL. Your agent opens that URL and Ringee handles caller ID selection, credit checks and the WebRTC call.

Click-to-call is the fastest way to add calling to an existing CRM: one server-side request, one redirect, no frontend SDK. If you want the dialer to live inside your own UI instead of a Ringee tab, use the Dialer SDK.

Request

curl -X POST https://api.ringee.io/api/integrations/custom/click-to-call \
  -H "Content-Type: application/json" \
  -H "X-Ringee-Api-Key: cik_live_xxxxxxxx…" \
  -d '{
    "contactExternalId": "ext_contact_42",
    "agentEmail": "rep@example.com"
  }'

Field	Type	Required	Description
`contactExternalId`	string	Conditional	Contact id previously linked through `contact.upserted`
`phoneNumber`	string	Conditional	Destination number; required if the external contact does not resolve to a number
`fromNumber`	string	No	Explicit caller ID; otherwise Ringee resolves one
`agentEmail`	string	Conditional	Ringee member who will place the call; required in organizations unless `ownerEmail` is sent
`ownerEmail`	string	Conditional	Alias for `agentEmail` when your CRM models a record owner
`ownerExternalId`	string	No	Reserved; it cannot currently resolve the agent by itself

Send at least contactExternalId or phoneNumber. If both resolve a destination, the explicit phoneNumber wins. An unknown contactExternalId can still be used with phoneNumber, and the returned contactId will be null.

Response

A successful request returns 201 Created:

{
  "contactId": "6b2f8f1e-6a2e-4f1c-9a3d-2d1b0c7e4a55",
  "agentUserId": "a91c4d77-1f0b-4a2e-8c3d-77b1e2f4a9c0",
  "toNumber": "+14155550123",
  "fromNumber": "+14155550100",
  "dialerUrl": "https://app.ringee.io/dashboard/dialer?session=…",
  "sessionToken": "eyJhbGciOi…",
  "expiresAt": "2026-09-04T14:05:00.000Z"
}

Field	Description
`contactId`	Ringee contact UUID, or `null` when calling a raw number
`agentUserId`	Ringee user authorized for the call
`toNumber`	Resolved destination number
`fromNumber`	Selected caller ID
`dialerUrl`	URL to open in the browser; valid for 5 minutes
`sessionToken`	Same signed authorization already embedded in `dialerUrl`
`expiresAt`	ISO-8601 expiry for the session

Pass only dialerUrl and expiresAt to your frontend. Do not expose the separate sessionToken field, persist it, or write it to logs. The token is already inside dialerUrl, so treat that URL as sensitive and short-lived too.

Agent resolution

Workspace	Behavior
Personal	The workspace owner always places the call. `agentEmail` is ignored.
Organization	`agentEmail` (or `ownerEmail`) must match a member of that organization, or the request fails with 422.

Take agentEmail from your authenticated session, not from a value the browser sent. Otherwise any user could place calls as any colleague.

ownerExternalId is accepted in the payload but is not yet wired to a resolution strategy — sending it without agentEmail returns 422. Use agentEmail.

Caller ID resolution

An explicit fromNumber is normalized and used as the caller ID. When you do not send it, Ringee picks one in this order:

the agent’s first active verified caller ID in that workspace;
any purchased number on the workspace;
otherwise the request fails with 422 No caller ID or purchased number is available for this workspace.

Wiring the button

Keep the call server-side

The request must be made by your backend (or an Edge Function). The cik_live_ key must never reach the browser.

Pre-open the tab

Open a blank tab before the async request so popup blockers do not swallow it, then navigate it once you have the URL.

const tab = window.open("", "_blank");

try {
  const { dialerUrl } = await fetch("/api/ringee/click-to-call", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ contactExternalId: contact.id }),
  }).then((r) => r.json());

  tab!.location.href = dialerUrl;
} catch (error) {
  tab?.close();
  showError(error);
}

Guard the button

Disable it when the contact has no valid phone number, or when the contact is on the Do Not Call list. Ringee blocks DNC numbers server-side too, but failing early is a better experience.

Never auto-dial

Do not request a dialer URL on page load. Calls must start from a real click.

Errors

Status	Cause
400	Neither `contactExternalId` (linked to a contact) nor `phoneNumber` was provided.
401	Missing or invalid `X-Ringee-Api-Key`.
422	`agentEmail` missing on an organization workspace, no member matched the email, or no caller ID is available.

Next steps

Receive the call back

Log the call in your CRM when it ends

Embed the dialer instead

Keep agents inside your own UI

Authorizations

X-Ringee-Api-Key

string

header

required

The cik_live_ secret key of a Custom Integration. Shown once at creation. Server-side only.

Body

application/json

contactExternalId

string

The contact's id in your CRM. Resolves to a Ringee contact if you previously synced it with contact.upserted.

Example:

"ext_contact_42"

phoneNumber

string

Destination number. Required unless contactExternalId resolves to a contact that already has one. When both are provided, this explicit number wins.

Example:

"+14155550123"

agentEmail

string

Email of the Ringee user who will place the call. Required for organization workspaces unless ownerEmail is provided. Take it from your authenticated session, never from a value the browser sent.

Example:

"rep@example.com"

fromNumber

string

Caller ID to use. Defaults to the agent's first active verified caller ID, then any purchased number on the workspace.

Example:

"+14155550100"

ownerEmail

string

Alias for agentEmail, used when your CRM models this as a record owner.

ownerExternalId

string

Accepted but not yet wired to a resolution strategy. Sending it without agentEmail returns 422 — use agentEmail.

Response

A dialer session was created.

contactId

string | null

required

The Ringee contact, when contactExternalId resolved to one. null otherwise.

Example:

"6b2f8f1e-6a2e-4f1c-9a3d-2d1b0c7e4a55"

agentUserId

string

required

The Ringee user who will place the call.

Example:

"a91c4d77-1f0b-4a2e-8c3d-77b1e2f4a9c0"

toNumber

string

required

Destination normalized toward E.164 when possible.

Example:

"+14155550123"

fromNumber

string

required

The caller ID Ringee selected.

Example:

"+14155550100"

dialerUrl

string<uri>

required

The URL to open. Valid for 5 minutes.

Example:

"https://app.ringee.io/dashboard/dialer?session=eyJhbGciOi...&to=%2B14155550123&from=%2B14155550100"

sessionToken

string

required

The signed session, already embedded in dialerUrl. Do not expose this field separately, persist it, or write it to logs — it authorizes a call on the agent's behalf.

expiresAt

string<date-time>

required

Expiry of the dialer session.

Example:

"2026-05-23T14:35:00.000Z"

curl --request POST \
  --url https://api.ringee.io/api/integrations/custom/click-to-call \
  --header 'Content-Type: application/json' \
  --header 'X-Ringee-Api-Key: <api-key>' \
  --data '
{
  "contactExternalId": "ext_contact_42",
  "agentEmail": "rep@example.com"
}
'

{
  "contactId": "6b2f8f1e-6a2e-4f1c-9a3d-2d1b0c7e4a55",
  "agentUserId": "a91c4d77-1f0b-4a2e-8c3d-77b1e2f4a9c0",
  "toNumber": "+14155550123",
  "fromNumber": "+14155550100",
  "dialerUrl": "https://app.ringee.io/dashboard/dialer?session=eyJhbGciOi...&to=%2B14155550123&from=%2B14155550100",
  "sessionToken": "eyJhbGciOi...",
  "expiresAt": "2026-05-23T14:35:00.000Z"
}

{
  "statusCode": 400,
  "message": "Must provide either contactExternalId (linked to a contact) or phoneNumber",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Must provide either contactExternalId (linked to a contact) or phoneNumber",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Must provide either contactExternalId (linked to a contact) or phoneNumber",
  "error": "Bad Request"
}

Get Started

CRM to Ringee

Ringee to CRM

Guides

Request

Response

Agent resolution

Caller ID resolution

Wiring the button

Errors

Next steps

Receive the call back

Embed the dialer instead

Authorizations

Body

Response

​Request

​Response

​Agent resolution

​Caller ID resolution

​Wiring the button

​Errors

​Next steps

Receive the call back

Embed the dialer instead

Authorizations

Body

Response

Request

Response

Agent resolution

Caller ID resolution

Wiring the button

Errors

Next steps