Skip to main content

Test Environment for Contacts with Shared Username

  • Updated

  1. Overview

  2. Endpoint

  3. Request Fields

  4. Rules

  5. Request

  6. Payload Structure

  7. When to Use

  8. Possible Errors

  9. Considerations

 

Overview

Blip provides an endpoint to register contacts that will be used for tests associated with a phone number on WhatsApp. In this test scenario, the registered contact behaves as a contact that has adopted the username feature and therefore does not share the phone number. This contact will be created with a GUID as the contact’s identity.

The endpoint allows you to provide basic contact information, such as display name and phone number, through a set request directed to the /phone-numbers/test-contacts resource.

This resource can be used in scenarios where it is necessary to configure or update test contacts for validating integrations and functionalities related to the WhatsApp username.

 

Endpoint

The operation is performed through the organization’s commands endpoint:

POST https://{ORGANIZATION_ID}.http.msging.net/commands

Headers

Content-Type: application/json
Authorization: Key {YOUR_TOKEN}

Where:

  • ORGANIZATION_ID: identifier of the organization/account in Blip.

  • YOUR_TOKEN: bot authorization key used to make the request.
     

Request Fields

The request uses the Blip platform command format.

Field Description
id Unique identifier of the request. Can be generated automatically, for example, using {{$guid}}.
to Recipient of the command. For this operation, postmaster@wa.gw.msging.net must be used.
method Operation method. For registering or updating the contact, set must be used.
type Type of resource sent in the request. Must be application/vnd.iris.whatsapp.phonenumber+json.
uri Resource to be manipulated. For test contacts, it must be /phone-numbers/test-contacts.
resource Object containing the test contact’s data.
resource.displayName Display name of the test contact. (optional)
resource.number Phone number associated with the contact.

 

Rules

For a number to be registered as a Test Contact, some rules must be followed:

  • The number must be new, meaning it must not already be registered as a Test Contact.

  • It is allowed to register up to 2 numbers as Test Contacts.

  • The number cannot have been previously used to chat with the Bot.

  • The number must be provided in international format, including the country code. Example: +5511999999999

⚠️ Important: it is not possible to delete a number from the test environment. Once the number is added, it will always behave as a number created as a GUID. This state cannot be revoked.
 

Request

Example request to register a test contact:

POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}
{
    "id": "{{$guid}}",
    "to": "postmaster@wa.gw.msging.net",
    "method": "set",
    "type": "application/vnd.iris.whatsapp.phonenumber+json",
    "uri": "/phone-numbers/test-contacts",
    "resource": {
        "displayName": "test",
        "number": "+5511999999999"
    }
}

Example of the data used

In the example above:

  • Contact name: test

  • Number: +5511999999999

  • Method: set

  • Resource: /phone-numbers/test-contacts

The number must be provided in international format, including the country code.
 

Payload Structure

The resource object contains the information of the contact to be configured:

"resource": {
    "displayName": "test",
    "number": "+5511999999999"
}

displayName (optional)

Represents the display name associated with the test contact.

Example:

"displayName": "test"

number

Represents the contact’s phone number in the format +CC_AREA_NUMBER

Example:

"number": "+5511999999999"

It is recommended to provide the number using the international format, including the + and country code.
 

When to Use

The endpoint can be used in scenarios where it is necessary to configure test contacts without known phone numbers related to WhatsApp phone numbers, for example:

  • Testing WhatsApp-related functionalities;

  • Configuring contacts used in test environments;

  • Automating the registration of test contacts;

  • Updating the data of a test contact.

Note: replace {ORGANIZATION_ID} with the corresponding organization and {YOUR_TOKEN} with a valid authorization key before making the call.
 

Possible Errors

While using the /phone-numbers/test-contacts endpoint, some situations may prevent the registration of the test contact.

1. Contact cannot be registered as test contact

Description:

This error may occur when the contact does not meet the necessary criteria to be used as a test number. 

2. Maximum number of test contacts

Description:

Indicates that the maximum allowed number of test contacts has already been reached.

If the Test Contact registration is successful, the API will return HTTP Status 200 (OK), indicating that the operation was completed successfully. 
 

Considerations

The endpoint must be used exclusively for managing test contacts supported by the /phone-numbers/test-contacts resource.

The resource structure must comply with the format expected by the endpoint, especially the displayName and number fields.


 

Need more help? Explore our content at Blip Academy or Blip Community, watch tutorials on our YouTube channel or ask your questions in our support channel 😃

Related articles