Skip to main content
POST
Authenticate a widget user by phone number
Call this endpoint from your backend with an API key that has the widget:write scope. It returns the same verified token as Authenticate contact. Pass that token to the widget through user.token.
  • Matching: spaces and a leading + in the number you send don’t matter, so +14155550123, 14155550123, and +1 415 555 0123 all identify the same contact.
  • Several matches: when more than one contact has the number, the one created first is used. Contacts created with Authenticate contact by external ID are never matched by phone.
  • No match: a new contact is created with the phone number and the fields you send.
  • Profile fields: name, language, customData, chat_context, and http_action_overrides are optional and saved on the contact, as in Authenticate contact. A field you send replaces the contact’s value, and customData keys are merged into the existing ones.
  • Personal access: mcp_access applies only to the returned token and is not saved, so send it on every call that needs it. The exception is mcp_access.credentials: those tokens are saved for the contact, as in Authenticate contact.
  • Validation: the number must include its country code. A national-only number such as 0770096918 is rejected with 400.
This endpoint does not accept email. For customers with an email, use Authenticate contact.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
phone
string
required

Phone number including the country code, e.g. +14155550123

mcp_access
object
name
string
language
enum<string>
Available options:
en,
fr,
de,
nl,
pl,
pt,
es,
it,
ru,
ja,
ko,
zh,
ar,
tr,
sv,
da,
no,
fi,
el,
cs,
hu,
th,
vi,
id,
he,
hi,
uk,
ro,
bg,
hr,
sk,
sl,
sr,
et,
lv,
lt,
is,
ga,
ms,
tl,
fa,
bn,
ta,
te,
ur,
sw,
zu,
af,
sq,
hy,
az,
eu,
be,
bs,
ca,
cy,
ku,
ckb,
kmr
customData
object
chat_context
string
http_action_overrides
object

Response

Default Response

token
string
required

The JWT token to use for further requests

contact
object
required