Handle an incoming message

Note:

Before you can get started, you need to do the following:

Using the Conversation API, you can receive and respond to messages from any channel you have configured. This tutorial shows you how to set up a .Net Core MVC application that receives and responds to messages.

Note:

This tutorial is easier to accomplish if you have already completed the steps for Sending a message.

Steps:
  1. Set up your .Net Core application
  2. Configure your Conversation API webhook
  3. Test the application

Set up your .Net Core application

  1. Create a new folder where you want to keep your app project. Then, open a command prompt to that location.
  2. Create a new .Net Core MVC app with the following command:
    Copy
    Copied
    dotnet new mvc
  3. Add the Newtonsoft.Json NuGet package.
    Copy
    Copied
    dotnet add package Newtonsoft.Json

Modify your application

Note:

This tutorial uses basic authentication for testing purposes. We recommend OAuth 2.0 authentication in a production environment. Read more about authentication methods here.

  1. In the Controllers folder of your project, create a new file named IncomingController.cs. Populate that file with the provided "IncomingController.cs" code found on this page. This code starts a server that listens for incoming messages. It then sends a text message in response.
Note:

This sample code is configured for the US region. If your Conversation API app wasn't created in the US region, replace all instances of https://us.conversation.api.sinch.com with https://eu.conversation.api.sinch.com in the sample code.

IncomingController.cs

This code sample is to be used with the instructions on this page to build a web server that will handle and respond to incoming messages.

// Get your Access Key and Access Secret at dashboard.sinch.com/settings/access-keys
using System;
using System.Net.Http;
using System.Net;
using System.Text;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Newtonsoft.Json;

public class IncomingMessage
{
    public string app_id {get; set;}
    public string accepted_time {get; set;}
    public string event_time {get; set;}
    public string project_id {get; set;}
    public ContactMessage message {get; set;}
    public Message_Delivery_Report message_delivery_report {get; set;}
    public string message_metadata {get; set;}
}
public class ContactMessage
{
    public string id {get; set;}
    public string direction {get; set;}
    public Contact_Message contact_message {get; set;}
    public ChannelIdentity channel_identity {get; set;}
    public string conversation_id {get; set;}
    public string contact_id {get; set;}
    public string metadata {get; set;}
    public string accept_time {get; set;}
}
public class Contact_Message
{
    public TextMessage text_message {get; set;}
}
public class TextMessage
{
    public string text {get; set;}
}
public class ChannelIdentity
{
    public string channel {get; set;}
    public string identity {get; set;}
    public string app_id {get; set;}
}
public class Message_Delivery_Report
{
    public string message_id {get; set;}
    public string conversation_id {get; set;}
    public string status {get; set;}
    public Channel_Identity channel_identity {get; set;}
    public string contact_id {get; set;}
    public string metadata {get; set;}
}

public class IncomingController : Controller
{
    public string accessKey = "Access_Key";
    public string accessSecret = "Access_Secret";

    [HttpPost]
    public async Task<HttpResponseMessage> ReceiveMessage([FromBody]IncomingMessage incomingMessage)
    {
        HttpResponseMessage res = new HttpResponseMessage();
        try
        {
            Console.WriteLine(incomingMessage.app_id);
            
            if (incomingMessage.message != null) 
            {
                Console.WriteLine(incomingMessage.message.contact_message.text_message.text);
                SendMessage sendMessage = new SendMessage(incomingMessage.app_id, 
                                                          incomingMessage.message.channel_identity.channel, 
                                                          incomingMessage.message.channel_identity.identity,
                                                          incomingMessage.message.contact_message.text_message.text);
                var response = await sendMessage.send(sendMessage, accessKey, accessSecret, incomingMessage.project_id);
                res.Content = new StringContent(response);
                Console.WriteLine(response);    
            }
            res.StatusCode = HttpStatusCode.OK;
            return res;
        }
        catch
        {
            res.StatusCode = HttpStatusCode.BadRequest;
            return res;
        }
    }
}

public class Recipient
{
    public Identified_By identified_by {get; set;}

    public Recipient(string channel, string identity)
    {
        identified_by = new Identified_By(channel, identity);
    }
}
public class Identified_By
{
    public Channel_Identity[] channel_identities {get; set;}

    public Identified_By(string channel, string identity)
    {
        channel_identities = new Channel_Identity[] { new Channel_Identity(channel, identity) };
    }
}
public class Channel_Identity
{
    public string channel {get; set;}
    public string identity {get; set;}

    public Channel_Identity(string channelVar, string idVar)
    {
        channel = channelVar;
        identity = idVar;
    }
}
public class Message
{
    public Text_Message text_message {get; set;}

    public Message(string text)
    {
        text_message = new Text_Message(text); 
    }
}
public class Text_Message
{
    public string text {get; set;}

    public Text_Message(string textVar)
    {
        text = "You sent: " + textVar;
    }
}

public class SendMessage
{
    public string app_id {get; set;}
    public Recipient recipient {get; set;}
    public Message message {get; set;}

    public SendMessage(string appIdVar, string channel, string identity, string text)
    {
        app_id = appIdVar;
        recipient = new Recipient(channel, identity);
        message = new Message(text);
    }   
    
    public string encodeAuth(string key, string secret)
    {
        var plainTextBytes = Encoding.UTF8.GetBytes(key + ":" + secret);
        return Convert.ToBase64String(plainTextBytes);
    }

    public async Task<string> send(SendMessage sendMessage, string key, string secret, string projectId)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", "Basic " + encodeAuth(key, secret));
            string json = JsonConvert.SerializeObject(sendMessage);
            var postData = new StringContent(json, Encoding.UTF8, "application/json");
            var request = await client.PostAsync("https://us.conversation.api.sinch.com/v1/projects/" + projectId + "/messages:send", postData);
            var response = await request.Content.ReadAsStringAsync();

            return response;
        }
    } 
}
  1. Assign your values to the following parameters:
ParameterYour value
Access_KeyFind your access key on your Sinch dashboard.
Access_SecretFind your access secret on your Sinch dashboard.
Note: Access secrets are only available during initial key creation.
  1. Save the file.
  2. Compile your application by executing the following command:
    Copy
    Copied
    dotnet build

Start your web server and set up a tunnel

  1. Start the server by executing the following command:
    Copy
    Copied
    dotnet run

    By default, your web server is started on port 5001.

  2. Now you need to open a tunnel to the server you just set up. We are using ngrok for this. if you don't have ngrok installed already you can install it with the following command:
    Copy
    Copied
    npm install ngrok -g
  3. Open a terminal or command prompt and enter:
    Copy
    Copied
    ngrok http https://localhost:5001
  4. Copy the HTTPS address that ends with .ngrok.io and add /Incoming/ReceiveMessage to the end of it.

Configure your webhook

For your application to receive messages from Conversation API, you must configure a webhook in your Conversation API app. For detailed instructions on configuring a webhook, click here.

  1. Set your webhook URL to the HTTP address you copied in the previous step.
  2. Assign the following triggers:
    • CONVERSATION_START
    • CONVERSATION_STOP
    • EVENT_DELIVERY
    • EVENT_INBOUND
    • MESSAGE_DELIVERY
    • MESSAGE_INBOUND
    • UNSUPPORTED

Test the application

Now that your server is running and your webhook is configured, you can test the application. From your messaging platform, send your Conversation API app a message. You will receive a message back in response on the messaging platform.

Additional resources

Read the links below to learn more:

Was this page helpful?

IncomingController.cs

This code sample is to be used with the instructions on this page to build a web server that will handle and respond to incoming messages.

// Get your Access Key and Access Secret at dashboard.sinch.com/settings/access-keys
using System;
using System.Net.Http;
using System.Net;
using System.Text;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Newtonsoft.Json;

public class IncomingMessage
{
    public string app_id {get; set;}
    public string accepted_time {get; set;}
    public string event_time {get; set;}
    public string project_id {get; set;}
    public ContactMessage message {get; set;}
    public Message_Delivery_Report message_delivery_report {get; set;}
    public string message_metadata {get; set;}
}
public class ContactMessage
{
    public string id {get; set;}
    public string direction {get; set;}
    public Contact_Message contact_message {get; set;}
    public ChannelIdentity channel_identity {get; set;}
    public string conversation_id {get; set;}
    public string contact_id {get; set;}
    public string metadata {get; set;}
    public string accept_time {get; set;}
}
public class Contact_Message
{
    public TextMessage text_message {get; set;}
}
public class TextMessage
{
    public string text {get; set;}
}
public class ChannelIdentity
{
    public string channel {get; set;}
    public string identity {get; set;}
    public string app_id {get; set;}
}
public class Message_Delivery_Report
{
    public string message_id {get; set;}
    public string conversation_id {get; set;}
    public string status {get; set;}
    public Channel_Identity channel_identity {get; set;}
    public string contact_id {get; set;}
    public string metadata {get; set;}
}

public class IncomingController : Controller
{
    public string accessKey = "Access_Key";
    public string accessSecret = "Access_Secret";

    [HttpPost]
    public async Task<HttpResponseMessage> ReceiveMessage([FromBody]IncomingMessage incomingMessage)
    {
        HttpResponseMessage res = new HttpResponseMessage();
        try
        {
            Console.WriteLine(incomingMessage.app_id);
            
            if (incomingMessage.message != null) 
            {
                Console.WriteLine(incomingMessage.message.contact_message.text_message.text);
                SendMessage sendMessage = new SendMessage(incomingMessage.app_id, 
                                                          incomingMessage.message.channel_identity.channel, 
                                                          incomingMessage.message.channel_identity.identity,
                                                          incomingMessage.message.contact_message.text_message.text);
                var response = await sendMessage.send(sendMessage, accessKey, accessSecret, incomingMessage.project_id);
                res.Content = new StringContent(response);
                Console.WriteLine(response);    
            }
            res.StatusCode = HttpStatusCode.OK;
            return res;
        }
        catch
        {
            res.StatusCode = HttpStatusCode.BadRequest;
            return res;
        }
    }
}

public class Recipient
{
    public Identified_By identified_by {get; set;}

    public Recipient(string channel, string identity)
    {
        identified_by = new Identified_By(channel, identity);
    }
}
public class Identified_By
{
    public Channel_Identity[] channel_identities {get; set;}

    public Identified_By(string channel, string identity)
    {
        channel_identities = new Channel_Identity[] { new Channel_Identity(channel, identity) };
    }
}
public class Channel_Identity
{
    public string channel {get; set;}
    public string identity {get; set;}

    public Channel_Identity(string channelVar, string idVar)
    {
        channel = channelVar;
        identity = idVar;
    }
}
public class Message
{
    public Text_Message text_message {get; set;}

    public Message(string text)
    {
        text_message = new Text_Message(text); 
    }
}
public class Text_Message
{
    public string text {get; set;}

    public Text_Message(string textVar)
    {
        text = "You sent: " + textVar;
    }
}

public class SendMessage
{
    public string app_id {get; set;}
    public Recipient recipient {get; set;}
    public Message message {get; set;}

    public SendMessage(string appIdVar, string channel, string identity, string text)
    {
        app_id = appIdVar;
        recipient = new Recipient(channel, identity);
        message = new Message(text);
    }   
    
    public string encodeAuth(string key, string secret)
    {
        var plainTextBytes = Encoding.UTF8.GetBytes(key + ":" + secret);
        return Convert.ToBase64String(plainTextBytes);
    }

    public async Task<string> send(SendMessage sendMessage, string key, string secret, string projectId)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", "Basic " + encodeAuth(key, secret));
            string json = JsonConvert.SerializeObject(sendMessage);
            var postData = new StringContent(json, Encoding.UTF8, "application/json");
            var request = await client.PostAsync("https://us.conversation.api.sinch.com/v1/projects/" + projectId + "/messages:send", postData);
            var response = await request.Content.ReadAsStringAsync();

            return response;
        }
    } 
}