Skip to main content

SMS And WhatsApp

In addition to conventional chatting, we provide the option for visitors to interact via SMS and WhatsApp from within the client. The details for this feature can be retrieved through the webSettings request, using the has_sms and whatsapp_number parameters to manage this behaviour.

SMS​

If the response from the webSettings query returns true for the has_sms field, it may be beneficial to display an option for the user to fill out a form to initiate a chat session via SMS.

A POST request will need to be made to https://chat2.visitor.chat/api/v2/chats/sms, the contents of the body should be the following json.

SMS Chat Request
{
  "installationId": 123,
  // Country `dial_code` from the supported countries below.
  "countryCode": "+44",
  "telephoneNumber": "7123456789",
  // Message content has a limit of 100 characters.
  "message": "Hello can I enquire about the McLaren 720s",
  // Captcha token is required as a field, but should always be an empty string.
  "captchaToken": "",
}

Error Responses​

Missing or invalid parameters
// Status Code 422
{
  "message": "The identifier field is required.",
  "errors": {
    "installationId": [
      "The installation id field is required."
    ],
    //...
  }
}

todo: Update error messages for SMS endpoints to allow the client to handle these scenarios.

Server error
// Status Code 500
/* Possible reasons for server error include
 * - Invalid country code
 * - Installation doesn't allow SMS sending
 * - Failed to send the SMS within our system
 */
{
  "message": "Server Error"
}
Example concept for SMS forms
Example concept for SMS forms

Country Codes​

At present, we support only a selection of country codes for SMS. Please note that this list may be updated in the future.

Country Codes.json
[
  {
    "name": "United Kingdom",
    "dial_code": "+44",
    "code": "GB"
  },
  {
    "name": "United States",
    "dial_code": "+1",
    "code": "US"
  },
  {
    "name": "Ireland",
    "dial_code": "+353",
    "code": "IE"
  }
]

WhatsApp​

If the response from the webSettings query returns a value for the whatsapp_number field, it may be beneficial to display an option for the user to fill out a form to initiate a chat session via WhatsApp.

Processing a request with WhatsApp is easier than with SMS, this is achieved by sending the visitor to a URL with the installation phone number and visitor message appended as parameters for WhatsApp to parse.

WhatsApp example
const whatsAppNumber = '447123456789';
const message = 'Hello can I enquire about the McLaren 720s';

window.open(encodeURI(`https://wa.me/${whatsAppNumber}?text=${message}`));
Example concept for WhatsApp forms
Example concept for WhatsApp forms
info

For further information regarding sending messages via WhatsApp, view their official documentation.