Contribute an Adapter
Adapters convert information provided by channels (SMS, Whatsapp) for each specific provider to xMessages and vise versa.
Setup the adapter repository to start working on it. Follow the steps given to add a new adapter & test it.
- 1.Fork the below repository & clone it.
https://github.com/samagra-comms/adapter/
- 2.Checkout to the recent branch. Eg. release-4.9.0
- 3.Open the project in any IDE spring/intellij.
- 4.
- 5.Write test cases for inbound method
convertMessageToXMsg
& outbound methodprocessOutBoundMessageF
. - 6.
All adapters are named as
<ProviderName><ChannelName>Adapter
; for example GupshupWhatsappAdapter. Adapters should extend AbstractProvider
and implement IProvider
. Thus, it needs to implement the following methods:public Mono<XMessage> convertMessageToXMsg(Object msg) // Converts API response object to XMessage
public Mono<XMessage> processOutBoundMessageF(XMessage nextMsg) //Converts XMessage object to API response and call it.
These methods are called by
inbound
and outbound
services internally to process the incoming and outgoing messages.Currently we accepts text/media/location/quickReplyButton/list messages. It should be implemeted according to the network provider(Netcore/Gupshup) documentation.
To enable these, we have to add them in
convertMessageToXMsg
and convert these according to the xMessage specWe can send a text message to user. This is the basic usage of an adapter. When creating a new adapter we should start with this scenario. A sample code for the same is also added here.
We can also send media/location/quickReplyButton/list messages to user. As we are using the ODK forms, we use bind::stylingTags, bind::caption to show the media file or to show the select choices as list/quick reply buttons. There are a few constraints which will be applied with the quickReplyButton/list content.
Below are the few styling tags we have allowed for now.
- image //To send image file
- audio //To send audio file
- video //To send video file
- document //To send document file
- buttonsForListItems //To send choices as quick reply buttons
- list //To send choices as list
To send this type of content to user, adapter should implement it according to the network provider(Netcore/Gupshup) documentation.
To make a bot use this adapter we will have to later add this adapter configuration in databse using the create adapter API. This adapter may require you to have some credentials, which can be stored in a vault service. Click here to see how to add a secret in vault.
Sample code to receive a text message from channel & reply to channel.
- 1.Create a new provider class which implements IProvider.
- Implement convertMessageToXMsg method for converting incoming message from channel to XMessage format.
- Implement processOutBoundMessageF method to reply to channel by converting XMessage format to channel message format.
public class ProviderChannelAdapter extends AbstractProvider implements IProvider {@Overridepublic Mono<XMessage> convertMessageToXMsg(Object message) throws JAXBException, JsonProcessingException {WebMessage webMessage = (WebMessage) message;SenderReceiverInfo from = SenderReceiverInfo.builder().deviceType(DeviceType.PHONE).build();SenderReceiverInfo to = SenderReceiverInfo.builder().userID("admin").build();XMessage.MessageState messageState = XMessage.MessageState.REPLIED;MessageId messageIdentifier = MessageId.builder().build();XMessagePayload xmsgPayload = XMessagePayload.builder().build();xmsgPayload.setText(webMessage.getText());XMessage.MessageType messageType= XMessage.MessageType.TEXT;from.setUserID(webMessage.getFrom());/* To use later in outbound reply message's message id & to */messageIdentifier.setChannelMessageId(webMessage.getMessageId());messageIdentifier.setReplyId(webMessage.getFrom());XMessage x = XMessage.builder().to(to).from(from).channelURI("web").providerURI("provider").messageState(messageState).messageId(messageIdentifier).messageType(messageType).timestamp(Timestamp.valueOf(LocalDateTime.now()).getTime()).payload(xmsgPayload).build();return Mono.just(x);}@Overridepublic Mono<XMessage> processOutBoundMessageF(XMessage xMsg) throws Exception {String phoneNo = "91" +xMsg.getTo().getUserID();OutboundMessage message = OutboundMessage.builder().message(Message.builder().title(xMsg.getPayload().getText()).choices(xMsg.getPayload().getButtonChoices()).msg_type("TEXT").build()).to(phoneNo).messageId(xMsg.getMessageId().getChannelMessageId()).build();String url = "http://example.com/replyMessageToChannel";return WebService.getInstance().sendOutboundMessage(url, outboundMessage).map(new Function<WebResponse, XMessage>() {@Overridepublic XMessage apply(WebResponse webResponse) {if(webResponse != null){xMsg.setMessageId(MessageId.builder().channelMessageId(webResponse.getId()).build());xMsg.setMessageState(XMessage.MessageState.SENT);}return xMsg;}});}} - 2.Create a web service class that handles api which is used to reply to channel.@Servicepublic class WebService {private final WebClient webClient;private static WebService webService = null;public WebService(){this.webClient = WebClient.builder().build();}public static WebService getInstance() {if (webService == null) {return new WebService();} else {return webService;}}public Mono<PwaWebResponse> sendOutboundMessage(String url, OutboundMessage outboundMessage) {return webClient.post().uri(url).body(Mono.just(outboundMessage), OutboundMessage.class).retrieve().bodyToMono(WebResponse.class).map(new Function<WebResponse, WebResponse>() {@Overridepublic WebResponse apply(WebResponse webResponse) {if (webResponse != null) {System.out.println("MESSAGE RESPONSE " + webResponse.getMessage());System.out.println("STATUS RESPONSE " + webResponse.getStatus());System.out.println("MESSAGE ID RESPONSE " + webResponse.getId());return webResponse;} else {return null;}}}).doOnError(new Consumer<Throwable>() {@Overridepublic void accept(Throwable throwable) {System.out.println("ERROR IS " + throwable.getLocalizedMessage());}});}}
- 3.Create a class for format which is accepted by reply to channel api Eg. http://example.com/replyMessageToChannel.@Getter@Setter@Builderclass OutboundMessage {private Message message;private String to;private String messageId;}
- 4.Create a message format class for OutboundMessage class property.@Getter@Setter@Builderclass Message {String title;private ArrayList<ButtonChoice> choices;private String msg_type;}
- 5.Create a class that accepts response from channel reply api.@Getter@Setterclass WebResponse {private String id;private String status;private String message;}
- 6.Create a class that accepts format for message received from channel.@Getter@Setterclass WebMessage extends CommonMessage {String messageId;String text;String from;}
- 7.If we want to fetch the credentials of the adapter from vault service, see the code of FirebaseNotificationAdapter to check how to do this.
After the adapter is created we should be able to implement it in inbound & outbound service for receiving and sending messages to user. Click here to see the process & sample code on how to to do this.
Last modified 9mo ago