Sunbird UCI
  • Overview of Sunbird UCI
  • 📙Learn
    • UCI use cases
    • UCI for Education(Case study)
    • Tech Overview
      • Glossary
      • High-level Architecture Design
      • Design Principles
      • Standards
  • 🚀Use
    • Choose your Persona
    • Adopter - Install and use UCI
      • Pre-requisites, Installation Setup, Post Setup
      • Setting up your very first conversation
      • API Documentation
      • Data Exhaust and Analytics
      • Posthog Event
      • Whatsapp (Netcore)
      • Environment Variables
    • Developer - Contribute to UCI
      • UCI Basics
        • XMessage Specification
        • Transformers
          • ODK Transformer
            • Interactive-Messages
            • Media Messages
            • Location
          • Broadcast Transformer
        • Adapters
          • Firebase Notification Adapter
        • User Segment
        • Schema Overview
          • UCI Core Schema
            • XMessage Schema
            • Assessment DB Schema
          • UCI API Schema
      • Development environment
        • Backend Setup
        • Setting up IDE
        • Environment variable setup
        • Debug services
        • Build and Execute UCI
        • Frontend Setup (Admin Console)
        • Frontend Setup (PWA)
        • Transport Socket
      • API Documentation
        • Bot Setup APIs
        • History APIs
        • Direct Message APIs
        • Vault APIs
      • Database Schema
        • Cassandra Xmessage Database
        • Postgres Forms Database
        • Postgres User Analytics Database
        • Postgres Comms Database
      • Contribution Guide
        • Your first PR
        • Contribute an Adapter
        • Adapter Implementation
        • Create a Transformer
    • Contact the administrator
  • ✅Releases
    • Release V2
  • 🤝Engage
    • Software License
    • Acceptable Use Policy
    • Terms of Service
    • Source Code
    • Discussion Forum
Powered by GitBook
On this page
  • 1. Overview
  • 2. How to setup adapter
  • 3. Creating your own Adapters
  • 3.1. Incoming content
  • 3.2. Outgoing Content
  • 4. Adapter Credentials
  • 5. Sample Code
  • 6. Adapter implementation
  • 7. List of Existing Adapter Implementations

Was this helpful?

Edit on GitHub
  1. Use
  2. Developer - Contribute to UCI
  3. Contribution Guide

Contribute an Adapter

PreviousYour first PRNextAdapter Implementation

Last updated 1 year ago

Was this helpful?

1. Overview

Adapters convert information provided by channels (SMS, Whatsapp) for each specific provider to xMessages and vise versa.

2. How to setup adapter

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 latest stable master branch.

  3. Open the project in any IDE spring/intellij.

  4. Follow to create a new adapter.

  5. Write test cases for inbound method convertMessageToXMsg & outbound method processOutBoundMessageF.

  6. A simple example to test the send text message is given in the .

3. Creating your own Adapters

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.

3.1. Incoming content

3.2. Outgoing Content

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

4. Adapter Credentials

5. Sample Code

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 {
        @Override
        public 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);
        }
    
        @Override
        public 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>() {
                @Override
                public 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.

    @Service
    public 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>() {
                        @Override
                        public 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>() {
                        @Override
                        public 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
    @Builder
    class OutboundMessage {
        private Message message;
        private String to;
        private String messageId;
    }
  4. Create a message format class for OutboundMessage class property.

    @Getter
    @Setter
    @Builder
    class Message {
        String title;
        private ArrayList<ButtonChoice> choices;
        private String msg_type;
    }
  5. Create a class that accepts response from channel reply api.

    @Getter
    @Setter
    class WebResponse {
        private String id;
        private String status;
        private String message;
    }
  6. Create a class that accepts format for message received from channel.

    @Getter
    @Setter
    class WebMessage extends CommonMessage {
        String messageId;
    
        String text;
    
        String from;
    }

6. Adapter implementation

7. List of Existing Adapter Implementations

All adapters with the above implementation will be valid. An example adapter can be found .

Currently we accepts text/media/location/quickReplyButton/list messages. It should be implemeted according to the network provider(Netcore/Gupshup) .

To enable these, we have to add them in convertMessageToXMsg and convert these according to the

We 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 .

To send this type of content to user, adapter should implement it according to the network provider(Netcore/Gupshup) .

To make a bot use this adapter we will have to later add this adapter configuration in databse using the API. This adapter may require you to have some credentials, which can be stored in a vault service. to see how to add a secret in vault.

If we want to fetch the credentials of the adapter from vault service, see the code of 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. to see the process & sample code on how to to do this.

🚀
here
documentation
xMessage spec
documentation
FirebaseNotificationAdapter
Click here
Gupshup-Whatsapp
Netcore-Whatsapp
UCI Web Channel
Firebase Adapter
file
point 3
here
Click here
create adapter