Initiate a WhatsApp conversation

Owned by Jérôme Vincendon (Unlicensed)
Last updated: Sept 20, 2021


WhatsApp for Business gives your organisation the possibility to initiate a conversation with your customers, when you have their consent. Social25 contains a method that handles the API call to the Social25 API. This method can be called from Apex, Flows and Processes. This article describes how to do this.

To access this functionality you will need to set up a Whatsapp business account and connect a phone number with Social25. There are two ways to initiate a conversation: programmatically or via the Social25 multichannel window. To initiate a conversation from the chat window , the multichannel window must be enabled and configured. Moreover,  you will need to retrieve the connected Whatsapp number that is able to initiate a conversation from the configured platforms in your Social25 config page.

Social25__Post_Conversation Method

The method you can use to create conversations is called Social25__Post_Conversation. To call this method, you need the user's WhatApp phone number and a Platform ID. This Platform ID refers to Social25 can be provided by the Social25 team. We suggest to save this value in a Custom Setting for easy retrieval.

This method will return two things:

  • User_Identifier
  • Conversation_Identifier’

You need to create a SocialPersona for every User_Identifier, and can relate this to the record currently holding the user information. The Conversation_Identifier should be placed on a Heroku_Conversation_Id__c field on the object from which you want to chat.

Call method from a Flow

  1. Add an Action element in the Flow Builder
  2. Choose Social25__Post_Conversation
  3. Fill in the following 2 input values:

Phone Number

This should be the user's WhatApp phone number. The Social25 API will use this phone number to initiate the conversation

Platform Id

This is the ID that the Social25 team provided.


This action has two output values:

Conversation IdentifierThis value should be placed on a Heroku_Conversation_Id__c field on the object from which you want to chat. The chat window will load the conversation based on this value.
User IdentifierThis value should be placed on the SocialPersona that you can in turn relate to the user's contact

If you want to trigger this Flow after a record update, you have to make sure that you do it asynchronously.

Call method from Apex

It is also possible to call this method from Apex. This requires a list with Social25.Post_Conversation.PostConversationRequest objects. For every request object the Platform ID and Phone Number should be filled in. You can use the foillowing code snippet:

//You can add multiple requests in one method call, for this a list is needed
List<Social25.Post_Conversation.PostConversationRequest> initiateConversationRequests = new List<Social25.Post_Conversation.PostConversationRequest>();

//Instantiate the request object 
Social25.Post_Conversation.PostConversationRequest initiateConversationRequest = new Social25.Post_Conversation.PostConversationRequest();
initiateConversationRequest.platform_id = '{The provided platform id}';
initiateConversationRequest.user_identifier = '{The mobile phone number}';

//Add the request object to the list
initiateConversationRequests.add(initiateConversationRequest);

//Call the 'Post Conversation' method, a list with the generated 'User_Identifiers' and 'Conversation_Identifiers' are returned
List<Social25.Post_Conversation.PostConversationResponse> responses = Social25.Post_Conversation.call(initiateConversationRequests);

for (Social25.Post_Conversation.PostConversationResponse initiateConversationResponse : responses) {
	String conversation_Identifier = initiateConversationResponse.conversation_id;
	String user_Identifier = initiateConversationResponse.user_id;
}


If you want to call this method after a record update you have to make sure that you do it in a future method.

FAQ

  • What should I do when a phone number is changed? Do this require a new API call?
    • Yes, unfortunately, we do not get an update when a phone number is changed. Therefore you will need to call the API again and create a new Social Persona

  • What response is returned if the passed number is not a valid Whatsapp number?
    • This will return a 400 Bad Request

Related articles

On this page