Contacts

WhatsApp status check

caution

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.

info

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.

1. 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).

2. Save the WhatsApp IDs for those phone numbers. Use the WhatsApp IDs to send messages and notifications.

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

info

At this time, there is no callback to inform you when a WhatsApp user joins or leaves the network.

caution

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.

caution

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 to no_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 to wait:

{
   "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 be null
• surname: STRING, allowed to be null
• location: LOCATION, allowed to be null
• language: ENUM, limited to ISO-639-3 country codes, allowed to be null
• opted_in: BOOLEAN, defaults to false
• opted_in_at: DATETIME, allowed to be null
• birthday: DATETIME, allowed to be null
• whatsapp_profile_name: STRING, allowed to be null
• whatsapp_id: STRING, allowed to be null

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.

caution

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 to ISO8601 formatted timestamps in the UTC timezone.
• BOOLEAN, restricted to true and false JSON boolean types.
• STRING
• FLOAT
• INTEGER
• ENUM which requires an extra enum 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
    }
}'

info

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
    }
}'

info

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.

caution

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.