Bot.Builder.Community.Adapters.Tcl.WhatsApp 2.0.3

Microsoft Bot Framework TCL Adapter for .NET

This package contains an adapter that communicates directly with the TCL WhatsApp API, and translates messages to and from bot framework.

How to Install

PM> Install-Package Bot.Builder.Community.Adapters.Tcl.WhatsApp

How to Use

Set the TCL API Credentials

To send API requests, you'll need to configure the Adapter with the WhatsApp Number, Auth Key and a Validation API Url. The adapter supports an array of configurations for each WhatsApp number.

You could create in the project an appsettings.json file to set the TCL WhatsApp credentials as follows:

  "AdapterConfigurations": [
    {
      "ApiBaseUrl": "https://api.in.kaleyra.io",    // Example Values
      "SID": "H2IN1847521127IN",                    // Example Values
      "AuthKey": "A223292a323423424b534603446b",    // Example Values
      "WhatsAppNumber": "911201231676"              // Example Values
    },
    {
      "ApiBaseUrl": "",
      "SID": "",
      "AuthKey": "",
      "WhatsAppNumber": ""
    }
  ]

Use TclWhatsAppAdapter in your App

TclWhatsAppAdapter provides a translation layer for BotBuilder so that bot developers can connect to TCL WhatsApp messages and have access to the TclWhatsAppAdapter API.

To add the TclWhatsAppAdapter to a bot, for example, an EchoBot, in the Startup class you should add:

public void ConfigureServices(IServiceCollection services)
{
    services.AddTclWhatsAppAdapter(Configuration);
}

Internally this line adds all the services required for the Adapter to run.

    services.Configure<List<AdapterConfiguration>>(configuration.GetSection(TclWhatsAppAdapterOptions.Tcl));
    services.AddSingleton<AdapterOptionsService>();

    services.AddSingleton<KioWhatsAppAdapter, KioWhatsAppAdapterWithErrorHandler>();
    services.AddHttpClient<IKioWhatsAppClient, KioWhatsAppClient>();
    services.AddSingleton<ToWhatsAppConverter>();
    services.AddSingleton<ToActivityConverter>();

Send a text message

Send a text message from bot using MessageFactory to create a new Activity.

    await turnContext.SendActivityAsync(MessageFactory.Text($"Hello World!"), cancellationToken);

Sending Media Messages

To Send a media message use MessageFactory to create a Bot Message with attachment. Fill in ContentType, ContentUrl and send it as Activity.

Supported content type

• image/jpeg
• video/mp4
• audio/mpeg
• application/pdf

    var reply = MessageFactory.Attachment(new Attachment
    {
        ContentType = "image/jpeg",
        ContentUrl = "https://cdn.pixabay.com/photo/2024/02/28/07/42/european-shorthair-8601492_640.jpg",
    });

    reply.Text = "Here is an image of cute cat";

    await turnContext.SendActivityAsync(reply, cancellationToken);

Support for WhatsApp CTA (Click To Action), Interactive List, Interactive Button

Version 1.0.4 onwards supports these WhatsApp message types.

Click To Action

Refer the below example on how to send click to action messages from bot.

        private async Task SendCtaAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            var interactiveMessage = new TclInteractiveMessage()
            {
                Type = TclInteractiveType.CtaUrl,
                Footer = new TclContent()
                {
                    Text = "Footer Text",
                },
                Header = new TclContent()
                {
                    Type = "text",
                    Text = "Header Text",
                },
                Body = new TclContent()
                {
                    Text = "Click here to visit the URL",
                },
                Action = new TclAction()
                {
                    Name = TclInteractiveType.CtaUrl,
                    Parameters = new TclParameter()
                    {
                        // Max Length 20 chars
                        DisplayText = "Click here",
                        Url = "https://www.microsoft.com",
                    },
                },
            };
            var attachment = new Attachment
            {
                ContentType = TclMimeType.WhatsAppInteractiveMessage,
                Content = interactiveMessage,
            };
            var reply = MessageFactory.Attachment(attachment);
            await turnContext.SendActivityAsync(reply, cancellationToken);
        }

Reply from Click To Action is not sent

Interactive List

Refer the below example on how to send click to Interactive List messages from bot.

Reply from Interactive List is sent in activity.Text and activity.ChannelData will contain payload. Also it will have context for replies to interactive messages.

        private async Task SendInteractiveListAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            var interactiveListMessage = new TclInteractiveMessage()
            {
                Type = TclInteractiveType.List,
                Footer = new TclContent()
                {
                    Text = "Footer Text",
                },
                Header = new TclContent()
                {
                    Type = "text",
                    Text = "Header Text",
                },
                Body = new TclContent()
                {
                    Text = "Click here to visit the URL",
                },
                Action = new TclAction()
                {
                    Button = "Button Text",
                    Sections = new List<TclSection>()
                    {
                        new TclSection()
                        {
                            Title = "Section Title",
                            Rows = new List<TclRow>()
                            {
                                new TclRow()
                                {
                                    Id = "1",
                                    Title = "Row Title",
                                    Description = "Row Description",
                                },
                                new TclRow()
                                {
                                    Id = "2",
                                    Title = "Row Title",
                                    Description = "Row Description",
                                }
                            },
                        },
                    }
                },
            };
            var attachment = new Attachment
            {
                ContentType = TclMimeType.WhatsAppInteractiveMessage,
                Content = interactiveListMessage,
            };
            var reply = MessageFactory.Attachment(attachment);
            await turnContext.SendActivityAsync(reply, cancellationToken);
        }

Interactive Buttons

Refer the below example on how to send click to Interactive Buttons messages from bot.

Reply from Interactive List is sent in activity.Text and activity.ChannelData will contain payload. Also it will have context for replies to interactive messages.

        private async Task SendInteractiveButtonsAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            var interactiveMessage = new TclInteractiveMessage()
            {
                Type = TclInteractiveType.Button,
                Body = new TclContent()
                {
                    Text = "Hi Pablo! Your gardening workshop is scheduled for 9am tomorrow. Use the buttons if you need to reschedule. Thank you!",
                },
                Footer = new TclContent()
                {
                    Text = "Lucky Shrub: Your gateway to succulents!™",
                },
                Action = new TclAction()
                {
                    Buttons = new List<TclButton>()
                    {
                        new TclButton()
                        {
                            Type = "reply",
                            Reply = new TclReply()
                            {
                                Id = "change-button",
                                Title = "Change",
                            },
                        },
                        new TclButton()
                        {
                            Type = "reply",
                            Reply = new TclReply()
                            {
                                Id = "cancel-button",
                                Title = "Cancel",
                            },
                        },
                    },
                },
            };
            var attachment = new Attachment
            {
                ContentType = TclMimeType.WhatsAppInteractiveMessage,
                Content = interactiveMessage,
            };
            var reply = MessageFactory.Attachment(attachment);
            await turnContext.SendActivityAsync(reply, cancellationToken);
        }

Flow Messages

Version 1.0.5 onwards supports these WhatsApp message types.

Refer the below example on how to send Flow messages from bot.

Response to the Flow is sent in activity.Text which is flow name and activity.ChannelData will contain payload

        private async Task SendFlowAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            var interactiveMessage = new TclInteractiveMessage()
            {
                Type = TclInteractiveType.Flow,
                Footer = new TclContent()
                {
                    Text = "Flow Footer Text",
                },
                Header = new TclContent()
                {
                    Type = "text",
                    Text = "Header Text",
                },
                Body = new TclContent()
                {
                    Text = "Flow Message Body",
                },
                Action = new TclAction()
                {
                    Name = TclInteractiveType.Flow,
                    Parameters = new TclParameter()
                    {
                        FlowMessageVersion = "3",
                        FlowAction = "navigate",
                        FlowToken = "unused",
                        FlowId = "1085669062",
                        FlowCta = "Open Flow!",
                        FlowActionPayload = new
                        {
                            Screen = "PICK_UP_PERSONAL"
                        }
                    },
                },
            };
            var attachment = new Attachment
            {
                ContentType = TclMimeType.WhatsAppInteractiveMessage,
                Content = interactiveMessage,
            };
            var reply = MessageFactory.Attachment(attachment);
            await turnContext.SendActivityAsync(reply, cancellationToken);
        }

Templates

Refer the below example on how to send Template messages from bot.

        private async Task SendTemplateAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            var interactiveMessage = new TclTemplateMessage()
            {
                Name = "orchestrate_media",
                Language = new TclLanguage()
                {
                    Code = TclLanguageType.English,
                },
                Components = new List<TclComponent>() {
                    new TclComponent()
                    {
                        Type = TclComponentType.Header,
                        Parameters = new List<TclTemplateParameter>()
                        {
                            new TclTemplateParameter()
                            {
                                Type = TclMessageType.Image,
                                Image = new TclImage()
                                {
                                    Link = "https://s3-whatsapp-messaging-image-storage-tata-api.s3.amazonaws.com/file2.png",
                                },
                            },
                        },
                    },
                    new TclComponent()
                    {
                        Type = TclComponentType.Body,
                        Parameters = new List<TclTemplateParameter>()
                        {
                            new TclTemplateParameter()
                            {
                                Type = TclMessageType.Text,
                                Text = "Body Text",
                            },
                            new TclTemplateParameter()
                            {
                                Type = TclMessageType.Text,
                                Text = "Body Text 2",
                            },
                        },
                    },
                    new TclComponent()
                    {
                        Type = TclComponentType.Button,
                        SubType = TclComponentType.Url,
                        Index = 0,
                        Parameters = new List<TclTemplateParameter>()
                        {
                            new TclTemplateParameter()
                            {
                                Type = TclMessageType.Text,
                                Text = "/whatsapp",
                            },
                        },
                    },
                    new TclComponent()
                    {
                        Type = TclComponentType.Button,
                        SubType = TclComponentType.Url,
                        Index = 1,
                        Parameters = new List<TclTemplateParameter>()
                        {
                            new TclTemplateParameter()
                            {
                                Type = TclMessageType.Text,
                                Text = "/whatsapp",
                            },
                        },
                    },
                }
            };
            var attachment = new Attachment
            {
                ContentType = TclMimeType.WhatsAppTemplateMessage,
                Content = interactiveMessage,
            };
            var reply = MessageFactory.Attachment(attachment);
            await turnContext.SendActivityAsync(reply, cancellationToken);
        }

Location

Refer the below example on how to send Location messages from bot.

        private async Task SendLocationAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            // send location as Entity
            var entity = new Entity();
            entity.SetAs(new GeoCoordinates
            {
                Latitude = 47.678581,
                Longitude = -122.131577,
                Name = "Microsoft Building 25"
            });

            var reply = MessageFactory.Text("");
            reply.Entities = new List<Entity> { entity };
            await turnContext.SendActivityAsync(reply, cancellationToken);
        }

Contact

Below sample shows how to send a contact from bot

        private async Task SendContactAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            var contact = new TclContactMessage()
            {
                // Name is required
                Name = new TclName()
                {
                    // Required
                    FormattedName = "John Doe",
                    FirstName = "John",
                },
                Addresses =
                [
                    new TclAddress()
                    {
                        Type = "HOME",
                        Street = "123 Main St",
                        City = "Redmond",
                        State = "WA",
                        Country = "USA",
                        Zip = "98052",
                        CountryCode = "1",
                    },
                ],
                Phones =
                [
                    new TclPhone()
                    {
                        Type = "HOME",
                        Phone = "14255551212",
                    },
                ],
                // Other fields - Birthday, Emails, Org, Urls
            };

            var attachment = new Attachment
            {
                ContentType = TclMimeType.WhatsAppContact,
                Content = contact,
            };
            var reply = MessageFactory.Attachment(attachment);
            await turnContext.SendActivityAsync(reply, cancellationToken);
        }