CRM contacts

Tell the dialer who the agent is looking at. The bundled UIs show the name and avatar, prefill the destination, and Ringee attributes the call to the right contact.

ringee.setContact({
  name: "Morgan Reed",
  number: "+13055550142",
  imageUrl: "https://crm.example.com/avatars/294.png",
  externalContactId: "crm-contact-294",
});

Fields

Field	Purpose
`name`	Visual label in the bundled UI
`number`	Prefills the destination
`imageUrl`	Avatar in the bundled UI
`contactId`	Native Ringee contact UUID
`externalContactId`	The contact’s id in your CRM

`contactId` or `externalContactId`?

You need one, not both.

contactId

Use it when you already know the internal Ringee UUID — for example because your app reads Ringee data directly.

externalContactId

Use it when your Custom Integration maps a CRM id to a Ringee contact.

externalContactId is the same value you send as data.externalId in contact.upserted. Sync contacts through the Public API first and Ringee resolves the link automatically.

Keeping externalContactId consistent is what makes the loop close: the call comes back to your CRM in call.completed carrying data.contact.externalId, so you can attach the activity to the right record without matching phone numbers.

Prefill just a number

When there is no contact record — a manual dial, an inbound lookup:

ringee.prefill("+13055550142");

Start a call directly

Floating can skip straight to dialing:

ringee.startCall({
  to: "+13055550142",
  name: "Morgan Reed",
  externalContactId: "crm-contact-294",
});

In Headless:

await dialer.call({
  to: "+13055550142",
  callerIdId: selectedCallerId,
  externalContactId: "crm-contact-294",
});

Phone number format

Destinations must be E.164 — a +, the country code, then the number, with no extension:

+13055550198
+34911234567
+18095550123

Anything else fails with INVALID_PHONE_NUMBER. Normalize in your CRM before passing it in; the SDK validates locally before it reaches the network.

Keeping it in sync

Call setContact() whenever the selected record changes. It is cheap and idempotent:

function onRecordOpened(contact) {
  ringee.setContact({
    name: contact.fullName,
    number: contact.phone,
    imageUrl: contact.avatarUrl,
    externalContactId: contact.id,
  });
}

To detach the current record — the user closed the panel, navigated away, deselected — pass null:

ringee.setContact(null);

After the call

The SDK emits ended with a call snapshot in the browser, but the durable record of what happened arrives through your outbound webhooks:

Event	Carries
`call.completed`	Direction, status, timing, duration
`call.outcome.updated`	The outcome the agent logged, plus the note
`recording.ready`	Recording URL and transcript

Write your CRM activity from the webhooks — they are signed, retried and idempotent. Use the browser events for live UI only.

Next steps

Sync contacts to Ringee

Establish the externalId link

Receive call activity

Close the loop back into your CRM

Get Started

Integration Modes

Guides

Reference

Operations

Fields

`contactId` or `externalContactId`?

contactId

externalContactId

Prefill just a number

Start a call directly

Phone number format

Keeping it in sync

After the call

Next steps

Sync contacts to Ringee

Receive call activity

​Fields

​contactId or externalContactId?

contactId

externalContactId

​Prefill just a number

​Start a call directly

​Phone number format

​Keeping it in sync

​After the call

​Next steps

Sync contacts to Ringee

Receive call activity

Fields

`contactId` or `externalContactId`?

Prefill just a number

Start a call directly

Phone number format

Keeping it in sync

After the call

Next steps