Contacts
WhatsApp status check
This API endpoint has been repurposed starting from WhatsApp Business API v2.43. This will no longer provide status information about a phone number.
Responses from this endpoint no longer return an 'invalid' status. A 'valid' status
and wa_id
will be provided for all requests, regardless of whether the phone number is connected to a WhatsApp account. There is no guarantee that the returned wa_id
will be valid. These changes are applicable for both direct responses, as well as webhook responses for non-blocking calls. WhatsApp will continue to return the same 'processing' and 'failed' responses as they do today.
The ability to check whether someone is available on the WhatsApp network is disallowed for Sandbox numbers. The sandbox will always return the status pending.
$ curl -X POST https://whatsapp.turn.io/v1/contacts \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '
{
"blocking": "wait",
"contacts": [
"+16315551003",
"+1-631-555-1002",
"+54 9 11 5612-1008",
"+1 (516) 283-7151"
]
}
'
> {
"contacts": [
{
"input": "+1-631-555-1002",
"status": "valid",
"wa_id": "16315551002"
},
{
"input": "+16315551003",
"status": "valid",
"wa_id": "16315551003"
},
{
"input": "+54 9 11 5612-1008",
"status": "valid",
"wa_id": "5491156121008"
},
{
"input": "+1 (516) 283-7151",
"status": "valid",
"wa_id": "15162837151"
}
]
}
Use this contacts endpoint only to get the WhatsApp ID for a phone number. However, there is no guarantee that the returned WhatsApp ID belongs to a WhatsApp account. Still, WhatsApp IDs are needed to send messages and use notifications.
As a business owner, you must present an option to opt-in to WhatsApp communications to your customers. The opt-in flow is managed by your business. After a customer opts-in, use the contacts endpoint to get the WhatsApp ID for a phone number.
Send a request containing an array of registered phone numbers to
/v1/contacts
. You will receive a response containing user statuses (status
) and their WhatsApp IDs (wa_id
).Save the WhatsApp IDs for those phone numbers. Use the WhatsApp IDs to send messages and notifications.
Repeat these steps on a regular basis to manage your list of WhatsApp IDs. The results are cached in the WhatsApp Business API client's database for 7 days.
Please ensure your code avoids relying on the status
and wa_id
parameters returned in this /v1/contacts
API endpoint response to determine whether the phone number is connected to a WhatsApp account or not. If a template message is sent to a phone number without a WhatsApp account, you will receive an error message denoting "User is not valid" with error code 1013. For non template messages, sending a message to a phone number without a WhatsApp account will return a 470 error.
At this time, there is no callback to inform you when a WhatsApp user joins or leaves the network.
We strongly recommend including the '+' prefix for the phone number payload. While you can submit numbers without the leading '+' we have encountered cases where WhatsApp will return 'invalid' despite the number being in use.
If you check too many phone numbers without sending to them, you will be banned. Take care to check only phone numbers critical to your business that you have already received opt-in for.
Parameters
Name | Required | Description |
---|---|---|
blocking | no | Options: no_wait (default) or wait . For more information, read the Blocking section. |
contacts | yes | Array of contact phone numbers. The numbers can be in any standard telephone number format. The recommended format for contact phone numbers is starting with a plus sign (+) and the country code. |
Blocking
There are two options for the blocking parameter: no_wait
and wait
. By default, if the blocking parameter is not specified in a call, blocking is no_wait
.
Blocking determines whether the request should wait for the processing to complete (synchronous) or not (asynchronous).
When blocking is not specified or is specified as
no_wait
, the processing of the phone numbers is asynchronous. This means that the status in the response will indicate processing and you will have to make another API call for those contacts to get the results.When blocking is specified as
wait
, the processing of the numbers is synchronous, meaning that you will see the final status for all of the contacts after syncing with server. This setting makes the query block wait until the numbers have all been checked, returning results. This might take some time.
Responses
This is with
blocking
set tono_wait
:
{
"contacts": [
{
"input": "1-631-555-1002",
"status": "processing"
},
{
"input": "6315551003",
"status": "processing"
},
{
"input": "+54 9 11 5612-1008",
"status": "processing"
},
{
"input": "+1 (516) 283-7151",
"status": "valid",
"wa_id": "15162837151"
}
]
}
After you send the request to get WhatsApp IDs you will receive a response with the current status of the requested numbers. Contacts that are new will typically have a status
of processing
as the application asynchronously determines their WhatsApp IDs.
If you use the "blocking": "wait"
option in the request, the response is now synchronous, so the response is generated only once the status of all of the numbers has been determined. This implies that the request will take a longer time to return if there are new contacts, but you will not see the "processing" value returned. The example code below demonstrates this behavior.
This is with
blocking
set towait
:
{
"contacts": [
{
"input": "1-631-555-1002",
"status": "valid",
"wa_id": "16315551002"
},
{
"input": "6315551003",
"status": "valid",
"wa_id": "16315551003"
},
{
"input": "+54 9 11 5612-1008",
"status": "valid",
"wa_id": "5491156121008"
},
{
"input": "+1 (516) 283-7151",
"status": "valid",
"wa_id": "15162837151"
}
]
}
Parameters
The contacts
response payload contains the same array of phone numbers sent in the request with the input
, status
, and wa_id
properties.
Name | Description |
---|---|
input | The value you sent in the contacts field of the JSON request. |
status | Status of the user. Options include: failed (Input check has failed), processing (Input is still being processed), valid (Input determined as WhatsApp ID) |
wa_id | WhatsApp user identifier that can be used in other API calls. |
Turn Contact Profile Api
By default the following fields are reserved, and immediately available, to all contacts in Turn:
name
: STRING, allowed to benull
surname
: STRING, allowed to benull
location
: LOCATION, allowed to benull
language
: ENUM, limited to ISO-639-3 country codes, allowed to benull
opted_in
: BOOLEAN, defaults tofalse
opted_in_at
: DATETIME, allowed to benull
birthday
: DATETIME, allowed to benull
whatsapp_profile_name
: STRING, allowed to benull
whatsapp_id
: STRING, allowed to benull
Any fields created using the /v1/contacts/schema
endpoint are created in addition to these fields.
To create additional fields, issue an HTTP POST
request to /v1/contacts/schemas
. This will create a new schema definition with a new uuid
.
From that point onwards, Turn will still return contacts according to previous schemas but will only allow writing of contacts according to the most recently created schema.
It is the responsibility of API clients to migrate contact profile details between schema changes.
$ curl -X POST https://whatsapp.turn.io/v1/contacts/schemas \
-H 'Authorization: Bearer token' \
-H 'Accept: application/vnd.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"version": "0.0.1-alpha",
"fields": [{
"name": "consent",
"display": "Consent Given",
"type": "BOOLEAN",
"default": false,
"is_private": true
}, {
"name": "gender",
"display": "Gender",
"type": "ENUM",
"null": false,
"is_private": false,
"default": "UNDISCLOSED",
"enum": [
{"value": "MALE", "display": "Male"},
{"value": "FEMALE", "display": "Female"},
{"value": "OTHER", "display": "Other"},
{"value": "UNDISCLOSED", "display": "Undisclosed"}
]
}]
}'
> {
"version": "0.0.1-alpha",
"uuid": "<the-new-schema-uuid>",
"fields": [{
"name": "consent",
"display": "Consent Given",
"type": "BOOLEAN",
"default": false,
"is_private": true
}, {
"name": "gender",
"display": "Gender",
"type": "ENUM",
"null": false,
"is_private": false,
"default": "UNDISCLOSED",
"enum": [
{"value": "MALE", "display": "Male"},
{"value": "FEMALE", "display": "Female"},
{"value": "OTHER", "display": "Other"},
{"value": "UNDISCLOSED", "display": "Undisclosed"}
]
}]
}
The response is the schema with the uuid
value identifying the schema in the payload.
The support field types are:
DATETIME
, restricted toISO8601
formatted timestamps in theUTC
timezone.BOOLEAN
, restricted totrue
andfalse
JSON boolean types.STRING
FLOAT
INTEGER
ENUM
which requires an extraenum
parameter that specifies the list of allowed values.LOCATION
which expects a{"latitude": ..., "longitude": ...}
object.
All fields can be configured to accept null
values by specifying "null": true
or "null": false
.
The only exception is the BOOLEAN
field type.
The BOOLEAN
field requires a default
value set to either true
or false
, it cannot be configured to allow null
values.
All fields must supply a default
value, this can be null
if "null": true
is specified, with the exception of BOOLEAN
fields.
The display
parameter is the human friendly display name for the field.
The name
parameter must be lower case, must start with a letter, and can only contain lower case alphanumeric characters and underscores.
The enum
parameter only accepts a list of options. Options are objects have a value
and a display
field. The value
must be upper case, must start with a letter, and can only contain upper case alphanumeric characters or underscores.
To retrieve an older schema do an HTTP GET
request to the /v1/contacts/schemas/<uuid>
endpoint.
Retrieve a Contact Profile
To retrieve a contact's profile details make a call to the /v1/contacts/<wa-id>/profile
endpoint
$ curl https://whatsapp.turn.io/v1/contacts/27123456789/profile \
-H 'Authorization: Bearer token' \
-H 'Accept: application/vnd.v1+json'
> '{
"version": "0.0.1-alpha",
"schema": "<the-schema-uuid>",
"generation": 0,
"fields": {
"language": "ENG",
"date_of_birth": null,
"age": 2,
"consent": false,
"location": null,
"name": null,
"risk_profile": 2.0,
"surname": null,
"birthday": null,
"opted_in": false,
"opted_in_at": null,
"whatsapp_id": null,
"whatsapp_profile_name": null
}
}'
To retrieve a contact profile for an earlier schema, supply the schema
uuid as a query parameter:
$ curl "https://whatsapp.turn.io/v1/contacts/27123456789/profile?schema=<the-schema-uuid>" \
-H 'Authorization: Bearer token' \
-H 'Accept: application/vnd.v1+json'
> '{
"version": "0.0.1-alpha",
"schema": "<the-schema-uuid>",
"generation": 0,
"fields": {
"language": "ENG",
"date_of_birth": null,
"age": 2,
"consent": false,
"location": null,
"name": null,
"risk_profile": 2.0,
"surname": null,
"birthday": null,
"opted_in": false,
"opted_in_at": null,
"whatsapp_id": null,
"whatsapp_profile_name": null
}
}'
The generation
field automatically increments by 1 for every change made to the contact's profile.
Replace a Contact Profile
To replace a contact's profile full details make an HTTP PUT
call to the /v1/contacts/<wa-id>/profile
endpoint. If the full set is not supplied, the defaults from the schema are applied for the missing fields.
$ curl -X PUT https://whatsapp.turn.io/v1/contacts/27123456789/profile \
-H 'Authorization: Bearer token' \
-H 'Accept: application/vnd.v1+json' \
-H 'Content-Type: application/json' \
-d '{"name": "Fizbo"}'
> '{
"version": "0.0.1-alpha",
"generation": 1,
"schema": "<the-schema-uuid>",
"fields": {
"language": nil,
"date_of_birth": null,
"age": 0,
"consent": false,
"location": null,
"name": "Fizbo",
"risk_profile": 0.0,
"surname": null,
"birthday": null,
"opted_in": false,
"opted_in_at": null,
"whatsapp_id": null,
"whatsapp_profile_name": null
}
}'
Please note that contact profile updates will always be validated according to the latest schema.
Update a Contact profile
To partially update a contact's profile make an HTTP PATCH
call to the /v1/contacts/<wa-id>/profile
endpoint and only supply the fields needing to be updated.
The details from the previous contact profile generation are automatically inherited.
$ curl -X PATCH https://whatsapp.turn.io/v1/contacts/27123456789/profile \
-H 'Authorization: Bearer token' \
-H 'Accept: application/vnd.v1+json' \
-H 'Content-Type: application/json' \
-d '{"name": "Fizbo"}'
> '{
"version": "0.0.1-alpha",
"generation": 2,
"schema": "<the-schema-uuid>",
"fields": {
"language": "ENG",
"date_of_birth": null,
"age": 2,
"consent": false,
"location": null,
"name": "Fizbo",
"risk_profile": 2.0,
"surname": null,
"birthday": null,
"opted_in": false,
"opted_in_at": null,
"whatsapp_id": null,
"whatsapp_profile_name": null
}
}'
Please note that partial contact profile updates will always be validated according to the latest schema.
Reset a Contact profile
To reset a contact's profile full details to the schema defaults make an HTTP DELETE
call to the /v1/contacts/<wa-id>/profile
endpoint.
Please note that this behaviour will delete the Contact's profile by resetting all of the values to their defaults, or null. If you want to delete the Contact itself, as well as the contact profile use the Chat deletion endpoint
$ curl -X DELETE https://whatsapp.turn.io/v1/contacts/27123456789/profile \
-H 'Authorization: Bearer token' \
-H 'Accept: application/vnd.v1+json' \
-H 'Content-Type: application/json'
> '{}'
[Deprecated] Retrieving Contact Profiles
The endpoint at /v1/export/contacts/details
has been deprecated. To export contact data, please use the Data Export API.