External Services Protocol
Also known as an ESP. Used by Interaction Server to communicate with servers that perform a specific service, when it is requested to do so. Such servers are called ESP servers. Classification Server is an ESP server, as is E-mail Server Java (when it generates an acknowledgment or autoresponse; when E-mail Server Java processes incoming or outgoing e-mail messages, it is a media server). You can create custom ESP servers by using the Genesys Open Media Platform SDK.
Glossary
Contents
Checking if a Contact Uses WhatsApp
This page describes how to verify whether a contact uses WhatsApp. Refer to the WhatsApp developer documentation for more information on how to use this feature.
Feature Deprecation
Genesys plans to update the WhatsApp Business API Client to the recommended version 2.45.1 before March 18, 2023, from its current version 2.41.3.
As a result, the behavior of the contacts endpoint will change. The response to contacts requests will no longer provide accurate status information about a phone number; it will always return a valid status and a WhatsApp ID, regardless of whether the phone number is associated with WhatsApp or not. Therefore, the WhatsApp ID returned may not always be valid.
If you use the ValidateContact feature as documented below, we recommend that you remove this request to avoid issues with your routing strategies and ensure that your business processes don't rely on the status of the WhatsApp ID returned.
The WhatsApp Business Platform On-Premises API changelog is available at https://developers.facebook.com/docs/whatsapp/on-premises/changelog.
Sending an ESP request
To verify whether a contact uses WhatsApp, your strategy must send an External Services Protocol (ESP) request that specifies the following:
- AppType—Enter the value 171, which is the application type for DMS, or select SocialMS in the ESP object in Interaction Routing Designer (IRD). This setting is not required if AppName is set in the request.
- AppName—Specify the name of the DMS Application, as defined in Configuration Sever.
- Service—Messaging
- Method—ValidateContact
Request parameters
| Parameter | Type | Value | Description |
|---|---|---|---|
| _umsChannel | string | The DMS channel name | Specify the DMS channel name for WhatsApp. You can omit this parameter if only one channel is configured in your environment. |
| Id | string | Contact phone number | Specify the contact's phone number. Refer to Recommended phone number formats for WhatsApp. |
Recommended phone number formats for WhatsApp
When there is no plus sign (+) at the beginning of the phone number, the country code is determined using the phone number that your WhatsApp Business On-Premises API client is registered under, so phone numbers associated with a different country code will fail.
The recommended best practice is to always specify the country code with the phone number and explicitly prefix it with a plus sign (+).Here are some examples that demonstrate this behavior, assuming the WhatsApp Business On-Premises API client is registered with an Indian phone number (i.e., country code is +91):
| Phone Number | Translated Phone Number | Valid? |
|---|---|---|
| "+1-631-555-1002" | "+16315551002" | Yes |
| "6315551002" | "+916315551002" | No |
| "1-631-555-1002" | "+9116315551002" | No |
| "+1 (516) 283-7151" | "+15162837151" | Yes |
| "+54 9 11 5612-1008" | "+5491156121008" | Yes |
Response parameters
| Parameter | Type | Value | Description |
|---|---|---|---|
| Id | string | Normalized contact phone number | If the contact was confirmed by WhatsApp, the value is the contact's normalized phone number. Otherwise, an empty string is returned. |
Error responses
| Error Code | Message |
|---|---|
| 900 | "%s %s" (generic error) |
| 901 | "%s connection with %s failed" |
| 701 | "Request is invalid: Service or Method name was not specified..." |
| 902 | "%s unknown %s" (might be "unknown service", "unknown method", "unknown service or method" or similar) |
| 904 | "%s incorrect %s" |
| 920 | "%s failed to execute request %s" |