*If you want to use the content of this page with an AI tool, or if you are an AI agent, use the Markdown version of this page: `https://developers.sinch.com/docs/conversation/getting-started.md`* *You may also connect to our documentation MCP server by clicking the **Connect MCP** button:* # Getting started Account required! Using Conversation API requires [signing up for a free account](https://community.sinch.com/t5/Customer-Dashboard/How-to-sign-up-for-your-free-Sinch-account/ta-p/8058) on the Sinch Build Dashboard. If you haven't already done so, [sign up now](https://dashboard.sinch.com/signup)! This guide will show you how to send a text message on Conversation API's SMS channel. You can use the principles included in this guide to send any message type on any channel supported by Conversation API. The structure of the API call is the same, regardless of the channel! To start sending messages: ## 1. Get access **Get access and create your access key:** Once you have created an account and logged in, select [Conversation API](https://dashboard.sinch.com/convapi/overview) from the left menu. Review the terms and conditions, select the **I agree to the terms and conditions** check box, and click **GET ACCESS** to proceed. Then, create your access key. Access keys are used to authenticate calls when using Conversation API. Access keys are generated in the [Sinch Build Dashboard](https://dashboard.sinch.com/settings/access-keys). If you need assistance, you can review [review our Community article on access key creation](https://community.sinch.com/t5/Conversation-API/How-to-get-your-access-key-for-Conversation-API/ta-p/8120). You'll need this info later! Make sure you have your access key, access key secret, and project ID readily available. This information will be required when making the API call to send the text message. The access key and access key secret must be recorded during access key creation. The project ID can be found on the Sinch Build Dashboard's [Project Settings](https://dashboard.sinch.com/settings/project-settings) page. ## 2. Create an app **Create a Conversation API app:** The next step is to create and configure a Conversation API app. Follow the instructions on the [Sinch Build Dashboard](https://dashboard.sinch.com/convapi/apps). You can also review [our Community article on app creation](https://community.sinch.com/t5/Conversation-API/How-to-create-a-Conversation-API-App/ta-p/8069). You'll need this info later! After you create your app, make sure you record your app's ID. This information will be required when making the API call to send the text message. ## 3. Configure the SMS channel **Configure the SMS channel:** To send and receive on the SMS channel, you have to complete some configuration steps. First, if you don't already have a number, click [here to learn how you can get a number from Sinch](https://community.sinch.com/t5/Account-Management/Buying-a-Number-from-Sinch/ta-p/8081). You'll need this info later! The sample code in this call makes use of the `SMS_SENDER` property, which needs to be populated with your Sinch number. Make sure you have that number readily available when making the API call. Once you have a Sinch number, activate the SMS channel through the [Sinch Build Dashboard](https://dashboard.sinch.com/convapi/overview). Select your **app** and click **SET UP CHANNEL** on the **SMS** row. Then, select your configured service plan from the drop-down box and confirm the integration. ## 4. Send the message Now you're ready to get started send a text message on Conversation API's SMS channel. If you already have experience making API calls, you can create an app that sends the text message in your preferred coding language. The payload, along with instructions on how to populate placeholder variables, is below. Alternatively, each tab features a guide that will walk you through setting up a simple application in the identified coding language (make sure you bring all the information you gathered during this process!): Payload The raw payload to send the text message is below: ```json { "app_id": "YOUR_app_id", "recipient": { "identified_by": { "channel_identities": [ { "channel": "SMS", "identity": "RECIPIENT_number" } ] } }, "message": { "text_message": { "text": "Hello from Sinch's Conversation API!" } }, "channel_properties": { "SMS_SENDER": "YOUR_sms_sender" } } ``` The placeholder values included in the payload above are detailed in the table below: | Placeholder value | Your value | | --- | --- | | `YOUR_app_id` | Your app ID, recorded in [step 2](#2.-create-an-app). Find your app ID on your Sinch [dashboard](https://dashboard.sinch.com/convapi/apps). | | `RECIPIENT_number` | The phone number of the recipient to which you want to send the message. | | `YOUR_sms_sender` | Your Sinch virtual phone number, recorded in [step 3](#3.-configure-the-sms-channel). This number is also available on the [Sinch Build Dashboard](https://dashboard.sinch.com/numbers/your-numbers). | Use the payload to make a `POST` API call to `https://us.conversation.api.sinch.com/v1/projects/YOUR_project_id/messages:send`, where `YOUR_project_id` is the project ID you recorded in [step 1](#1.-get-access). Include authentication information in the header. Since this guide is intended to testing purposes, you can use your access key and access key secret (also recorded in [step 1](#1.-get-access)) to authenticate using [basic authentication](/docs/conversation/api-reference/conversation#section/overview/basic-authentication) (we recommend using your access key and secret to create a short-lived [OAuth2.0](/docs/conversation/api-reference/conversation#section/overview/oauth2.0-authentication) token when working in production environments). Node ### Send a Conversation Message with the Sinch Node.js SDK Note: Before you can get started, you need the following already set up: - - [Node.js](https://nodejs.org/en/) and a familiarity with how to create a new app. First we'll create a Node project using npm. This creates a package.json and the core dependencies necessary to start coding. To create the project, do the following steps: 1. Create a folder called `send-conversation-app` 2. Navigate into the folder you created and run the following command. ```shell npm init ``` This command adds the package.json file. You will be prompted to provide values for the fields. For this tutorial, you can simply accept the default values and press enter at each stage. You can install the Sinch Node.js SDK using either [NPM](https://www.npmjs.com/) or [Yarn](https://yarnpkg.com/): NPM ```shell npm install @sinch/sdk-core ``` Yarn ```shell yarn add @sinch/sdk-core ``` Note: If you want to use the SDK with a javascript framework such as React or Angular, you can import it with an import statement. ```shell import {SinchClient} from `@sinch/sdk-core` ``` ### Create your Node file Create a new file named `index.js` in the project and paste the provided code into the file: index.js const { SinchClient } = require('@sinch/sdk-core'); const sinchClient = new SinchClient({ projectId: "YOUR_project_id", keyId: "YOUR_access_key", keySecret: "YOUR_access_secret" }); async function run(){ const response = await sinchClient.conversation.messages.send({ sendMessageRequestBody: { app_id: "YOUR_app_ID", recipient: { identified_by: { channel_identities: [ { channel: "SMS", identity: "RECIPIENT_number" } ] } }, message: { text_message: { text: "This is a test message using the Sinch Node.js SDK" } }, channel_properties: { SMS_SENDER: "YOUR_sms_sender" } } }); console.log(JSON.stringify(response)); } run(); ### Modify your Node application The code provided includes placeholder parameters. You'll need to update the parameters detailed in the following subsections with your values. Note: This sample code is configured for the US region. If your Conversation API app wasn't created in the US region, update you can set the region when you initialize the Sinch client: ```Javascript const sinchClient = new SinchClient({ projectId: "YOUR_project_id", keyId: "YOUR_access_key", keySecret: "YOUR_access_secret", region: Region.EUROPE }); ``` ##### Initialize the Node SDK client Before initializing a client using this SDK, you'll need three pieces of information: - Your Project ID - An access key ID - An access key Secret These values can be found on the [**Access Keys**](https://dashboard.sinch.com/settings/access-keys) page of the Sinch Build Dashboard. You can also [create new access key IDs and Secrets](https://community.sinch.com/t5/Conversation-API/How-to-get-your-access-key-for-Conversation-API/ta-p/8120), if required. Note If you have trouble accessing the above link, ensure that you have gained access to the [Conversation API](https://dashboard.sinch.com/convapi/overview) by accepting the corresponding terms and conditions. ##### Fill in remaining parameters for Node Assign your values to the following parameters: | Placeholder value | Your value | | --- | --- | | `YOUR_app_id` | Find your app ID on your Sinch [dashboard](https://dashboard.sinch.com/convapi/apps). | | `RECIPIENT_number` | The channel identity of the recipient to which you want to send the message. When using the `SMS` channel, this will be a phone number. | | `YOUR_sms_sender` | Your Sinch virtual phone number, available on the [Sinch Build Dashboard](https://dashboard.sinch.com/numbers/your-numbers). This is only required if you are using the `SMS` channel. | Ensure that you save the file. ### Send your first Conversation message using Node Now you can execute the code and send your test Conversation message. Run the following command: ```shell node index.js ``` You should receive a text to the phone number you entered and you'll see a response in your terminal or command prompt. You did it! Java ### Send a Conversation Message with the Sinch Java SDK Note: Before you can get started, you need the following already set up: - - [JDK 21 or later](https://www.oracle.com/java/technologies/downloads/) and a familiarity with how to create a new Java application. (The SDK itself only requires JDK 8 or later, but this quickstart guide uses JDK 21 as it is the latest version with long term support.) - [Apache Maven](https://maven.apache.org/install.html) and a familiarity with how to use the Maven CLI. To quickly get started setting up a simple client application using the Java SDK: 1. If you haven't already, clone the [sinch-sdk-java](https://github.com/sinch/sinch-sdk-java) repository. 2. Navigate to the `/examples/getting-started/conversation/send-text-message/src/main/resources` folder. 3. Open the `config.properties` [file](https://github.com/sinch/sinch-sdk-java/blob/main/examples/getting-started/conversation/send-text-message/src/main/resources/config.properties). Using the [access key credentials](https://dashboard.sinch.com/settings/access-keys) from your Sinch Build Dashboard, populate the following fields with your values: | Field | Description | | --- | --- | | `SINCH_PROJECT_ID` | The unique ID of your Project. | | `SINCH_KEY_ID` | The unique ID of your access key. | | `SINCH_KEY_SECRET` | The secret that goes with your access key. **Note:** For security reasons, this secret is only visible right after access key creation. | | `CONVERSATION_REGION` | This value must match the region of the Conversation app. Note that you'll only be able to use Conversation API apps configured for same region as the one associated with the server you target. See [the list of supported values](https://github.com/sinch/sinch-sdk-java/blob/main/client/src/main/com/sinch/sdk/models/ConversationRegion.java) for more information. | 4. Save the file. ### Modify your Java application 1. Navigate to the `/examples/getting-started/conversation/send-text-message/src/main/java/conversation/` folder and open the `Snippet.java` file. Snippet.java package conversation; import com.sinch.sdk.domains.conversation.api.v1.ConversationService; import com.sinch.sdk.domains.conversation.api.v1.MessagesService; import com.sinch.sdk.domains.conversation.models.v1.ChannelRecipientIdentities; import com.sinch.sdk.domains.conversation.models.v1.ChannelRecipientIdentity; import com.sinch.sdk.domains.conversation.models.v1.ConversationChannel; import com.sinch.sdk.domains.conversation.models.v1.messages.AppMessage; import com.sinch.sdk.domains.conversation.models.v1.messages.request.SendMessageRequest; import com.sinch.sdk.domains.conversation.models.v1.messages.response.SendMessageResponse; import com.sinch.sdk.domains.conversation.models.v1.messages.types.text.TextMessage; import java.util.Collections; import java.util.logging.Logger; public class Snippet { private static final Logger LOGGER = Logger.getLogger(Snippet.class.getName()); static void execute(ConversationService conversationService) { MessagesService messagesService = conversationService.messages(); String appId = "CONVERSATION_APPLICATION_ID"; String from = "SINCH_VIRTUAL_PHONE_NUMBER"; String to = "RECIPIENT_PHONE_NUMBER"; String body = "This is a test Conversation message using the Sinch Java SDK."; ChannelRecipientIdentities recipients = ChannelRecipientIdentities.of( ChannelRecipientIdentity.builder() .setChannel(ConversationChannel.SMS) .setIdentity(to) .build()); AppMessage message = AppMessage.builder() .setBody(TextMessage.builder().setText(body).build()) .build(); SendMessageRequest request = SendMessageRequest.builder() .setAppId(appId) .setRecipient(recipients) .setMessage(message) .setChannelProperties(Collections.singletonMap("SMS_SENDER", from)) .build(); LOGGER.info("Sending SMS Text using Conversation API"); SendMessageResponse value = messagesService.sendMessage(request); LOGGER.info("Response: " + value); } } 1. The code provided in **Snippet.java** includes placeholder parameters. Replace the following placeholder values for these parameters with your values: | Placeholder value | Your value | | --- | --- | | `CONVERSATION_APPLICATION_ID` | Find your app ID on your Sinch [dashboard](https://dashboard.sinch.com/convapi/apps). | | `RECIPIENT_PHONE_NUMBER` | The channel identity of the recipient to which you want to send the message. When using the `SMS` channel, this will be a phone number. | | `SINCH_VIRTUAL_PHONE_NUMBER` | Your Sinch virtual phone number, available on the [Sinch Build Dashboard](https://dashboard.sinch.com/numbers/your-numbers). This is only required when using the `SMS` channel. | 2. Save your file. ### Package the Java application Now that you've modified the application, you need to use the Maven CLI to create a package that you can then execute. Open a command prompt or terminal to the `examples/getting-started/conversation/send-text-message` folder and run the following command: ```Shell mvn package ``` This command creates the `target` folder and application. ### Send your first Conversation message using the Java SDK Now that your package is ready, you can send a text message to your mobile phone. To send the message, run the following code: ```Shell java -jar target/sinch-java-sdk-client-application-1.0-SNAPSHOT-jar-with-dependencies.jar ``` The console will display the response details received from the Sinch servers and you should receive an SMS message to the number you specified. .NET ### Send a message using .NET Note: Before you can get started, you need to do the following: - - [The latest version of .NET Core with **Long Term Support**](https://dotnet.microsoft.com/download) and a familiarity with how to create a new console application. To set up you .NET core application: 1. Create a new folder where you want to keep your app project. Then, open a terminal or command prompt to that location. 2. Create a new .NET Core console app with the following command: ```shell dotnet new console ``` 3. Add the `Newtonsoft.Json` NuGet package. ```shell dotnet add package Newtonsoft.Json ``` ### Modify your .NET 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](/docs/conversation/api-reference/conversation#section/overview/authentication). 1. Open the `Program.cs` file in your project folder. Replace all of the code in the `Main` method with the following code: ```csharp SendMessage sendMessage = new SendMessage("App_Id", "Channel", "Identity"); sendMessage.send(sendMessage, "Access_Key", "Access_Secret", "Project_Id"); Console.ReadLine(); ``` 2. Assign your values to the following parameters: | Parameter | Your value | | --- | --- | | `App_Id` | Find your app ID on your Sinch [dashboard](https://dashboard.sinch.com/convapi/apps). | | `Access_Key` | Find your access key on your Sinch [dashboard](https://dashboard.sinch.com/settings/access-keys). | | `Access_Secret` | Find your access secret on your Sinch [dashboard](https://dashboard.sinch.com/settings/access-keys). Note that access secrets are only available during initial key creation. | | `Project_Id` | Find your project ID on your Sinch [dashboard](https://dashboard.sinch.com/settings/project-management). | | `Channel` | The channel you want to use to send the message. Available channels are configured for the app on your Sinch [dashboard](https://dashboard.sinch.com/settings/access-keys). This guide assumes you've started with an `SMS` channel, but you can use any channel configured for your app. | | `Identity` | The channel identity of the contact to which you want to send the message. In the case of the `SMS` channel, this is the recipient's phone number. | 3. Save the file. 4. Next, create a new file in the project folder named `Message.cs`. Populate that file with the "Message.cs" code found on this page and save the file. This code sends a [text message](/docs/conversation/message-types/text-message/). Message.cs // Find your App ID at dashboard.sinch.com/convapi/apps // Find your Project ID at dashboard.sinch.com/settings/project-management // Get your Access Key and Access Secret at dashboard.sinch.com/settings/access-keys using System; using System.Net.Http; using System.Text; using Newtonsoft.Json; 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() { text_message = new Text_Message(); } } public class Text_Message { public string text {get; set;} public Text_Message() { text = "Text message from Sinch Conversation API."; } } 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) { app_id = appIdVar; recipient = new Recipient(channel, identity); message = new Message(); } public string encodeAuth(string key, string secret) { var plainTextBytes = Encoding.UTF8.GetBytes(key + ":" + secret); return Convert.ToBase64String(plainTextBytes); } public async void 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(); Console.WriteLine(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. 1. Before executing your code, you must first compile your application. Execute the following command: ```shell dotnet build ``` ### Send your first message using .NET Now you can execute the code and send your test message. Run the following command: ```shell dotnet run ``` You should receive a message in your configured messaging platform. Python ### Send a message using Python Note: Before you can get started, you need to do the following: - - [Python](https://www.python.org/) and a familiarity with how to create a new file. - Note that this tutorial uses basic authentication for testing purposes. We recommend OAuth 2.0 authentication in a production environment. Read more about [authentication methods](/docs/conversation/api-reference/conversation#section/overview/authentication). To quickly get started setting up a simple client application using the Python SDK: 1. If you haven't already, clone the [sinch-sdk-python](https://github.com/sinch/sinch-sdk-python) repository. 2. Navigate to the `examples/snippets` folder. 3. Copy the example `.env` file by running the following command: Linux/Mac ```bash cp .env.example .env ``` Windows (Command Prompt) ```cmd copy .env.example .env ``` Windows (Powershell) ```powershell Copy-Item .env.example .env ``` 1. Open the `.env` [file](https://github.com/sinch/sinch-sdk-python/blob/main/examples/snippets/.env.example) you just created. Using the [access key credentials](https://dashboard.sinch.com/settings/access-keys) from your Sinch Build Dashboard, populate the following fields with your values: | Field | Description | | --- | --- | | SINCH_PROJECT_ID | The unique ID of your Project. | | SINCH_KEY_ID | The unique ID of your access key. | | SINCH_KEY_SECRET | The secret that goes with your access key. **Note:** For security reasons, this secret is only visible right after access key creation. | 1. Save the file. 2. The Python SDK uses [Poetry](https://python-poetry.org/) to manage packages and dependencies, so install those dependencies using the following command: ```cmd poetry install ``` 1. Navigate to the `/examples/snippets/conversation/messages/send/` directory and open `snippet.py`. This code sends a [text message](/docs/conversation/message-types/text-message/). snippet.py """ Sinch Python Snippet This snippet is available at https://github.com/sinch/sinch-sdk-python/tree/main/examples/snippets """ import os from dotenv import load_dotenv from sinch import SinchClient load_dotenv() sinch_client = SinchClient( project_id=os.environ.get("SINCH_PROJECT_ID") or "MY_PROJECT_ID", key_id=os.environ.get("SINCH_KEY_ID") or "MY_KEY_ID", key_secret=os.environ.get("SINCH_KEY_SECRET") or "MY_KEY_SECRET", conversation_region=os.environ.get("SINCH_CONVERSATION_REGION") or "MY_CONVERSATION_REGION" ) # The ID of the Conversation App to send the message from app_id = "CONVERSATION_APP_ID" # The phone number of the recipient in E.164 format (e.g. +46701234567) recipient_identities = [ { "channel": "SMS", "identity": "RECIPIENT_PHONE_NUMBER" } ] response = sinch_client.conversation.messages.send_text_message( app_id=app_id, text="[Python SDK: Conversation] Sample text message", recipient_identities=recipient_identities ) print(f"Successfully sent text message.\n{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. 1. Assign your values to the following parameters: | Parameter | Your value | | --- | --- | | `appId` | Find your app ID on your Sinch [dashboard](https://dashboard.sinch.com/convapi/apps). | | `accessKey` | Find your access key on your Sinch [dashboard](https://dashboard.sinch.com/settings/access-keys). | | `accessSecret` | Find your access secret on your Sinch [dashboard](https://dashboard.sinch.com/settings/access-keys). Note that access secrets are only available during initial key creation. | | `projectId` | Find your project ID on your Sinch [dashboard](https://dashboard.sinch.com/settings/project-management). | | `channel` | The channel you want to use to send the message. Available channels are configured for the app on your Sinch [dashboard](https://dashboard.sinch.com/convapi/apps). This guide assumes you've started with an `SMS` channel, but you can use any channel configured for your app. | | `identity` | The channel identity of the contact to which you want to send the message. In the case of the `SMS` channel, this is the recipient's phone number. | 2. Save the file. ### Send your first message using Python Now you can execute the code and send your test message. Open a command prompt or terminal to the `/examples/snippets/conversation/messages/send/` directory and run the following command: ```shell python snippet.py ``` You should receive a message in your configured messaging platform. ## 5. Handle incoming messages Conversation API allows for two-way communication. In addition to sending messages, you can receive messages as well. Inbound messages are delivered via callback to a target URL. The payload of the callback contains the content of the message. Below is an example payload of an inbound message callback. To demonstrate Conversation API's ability to receive messages, click one of the language tabs. The corresponding guides will help you set up a simple application that can receive a message from a handset (for example, the handset to which you sent a message in step 4), process the message, and send the contents of the message back to your phone: Callback Below the example payload of an inbound message callback: ```JSON { "app_id": "01E3S8B6YCMRNR0GGM94H80ACX", "accepted_time": "2020-04-24T08:02:50.184581Z", "message": { "id": "01E6NKBV63YG6K01ENEW7S1N80", "direction": "TO_APP", "contact_message": { "text_message": { "text": "Hi from contact" } }, "channel_identity": { "channel": "SMS", "identity": "FROM_NUMBER", "app_id": "" }, "conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ", "contact_id": "01E6K4A8N3NANZ05VM0FS80EHD", "metadata": "{\"operator\":\"310150\"}", "accept_time": "2020-04-24T08:02:50.179021Z", "sender_id": "", "processing_mode": "CONVERSATION", "injected": false }, "message_metadata": "{\"arbitrary\": \"json object stringify as metadata\" }" } ``` Node ### Handling incoming messages using Node Note: Before you can get started, you need to do the following: - - [Node.js](https://nodejs.org/en/) and a familiarity with how to create a new app. - [ngrok](https://ngrok.com/). You'll use ngrok to open a tunnel to your local server. First we'll create a Node project using npm. This creates a package.json and the core dependencies necessary to start coding. To create the project, do the following steps: 1. Create a folder called `conv-receive` 2. Navigate into the folder you created and run the following command. ```shell npm init ``` This command adds the node_modules folder and the package.json file. You will be prompted to provide values for the fields. For this tutorial, you can simply accept the default values and press enter at each stage. 3. Add the fetch package with npm to generate the necessary dependencies. In this application, we are going to use Express to handle incoming requests. ```shell npm install cross-fetch npm install express ``` ### Create your Node file to handle incoming messages Note: This tutorial uses basic authentication for testing purposes. We recommend in a production environment you use OAauth 2.0 authentication. Read more about [authentication methods](/docs/conversation/api-reference/conversation#section/overview/authentication). Create a new file named `index.js` in the project and paste the provided "index.js" code found on this page into the file. index.js // Get your Access Key and Access Secret at dashboard.sinch.com/settings/access-keys const fetch = require('cross-fetch'); const express = require('express'); const app = express(); const port = 3000; app.use(express.json()); const ACCESS_KEY = ""; const ACCESS_SECRET = ""; app.post("/", async (req, res) => { var requestBody = req.body; console.log(requestBody); if (requestBody.message != undefined) { const sendMessage = { app_id: requestBody.app_id, recipient: { contact_id: requestBody.message.contact_id }, message: { text_message: { text: "You sent: " + requestBody.message.contact_message.text_message.text } }, channel_priority_order: [requestBody.message.channel_identity.channel] }; console.log(sendMessage); let result = await fetch( "https://us.conversation.api.sinch.com/v1/projects/" + requestBody.project_id + "/messages:send", { method: "POST", headers: { "Content-Type": "application/json", Authorization: 'Basic ' + Buffer.from(ACCESS_KEY + ":" + ACCESS_SECRET).toString('base64') }, body: JSON.stringify(sendMessage) } ); console.log(await result.json()); res.send("Ok"); } else { res.send("Ok"); } }); app.listen(port, () => { console.log("Listening at http://localhost:" + port); }); 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. This code starts a server that listens for incoming messages. It then sends a [text message](/docs/conversation/message-types/text-message/) in response. ### Fill in your Node parameters for handling incoming messages 1. Assign your values to the following parameters: | Parameter | Your value | | --- | --- | | `ACCESS_KEY` | Find your access key on your Sinch [dashboard](https://dashboard.sinch.com/settings/access-keys). | | `ACCESS_SECRET` | Find your access secret on your Sinch [dashboard](https://dashboard.sinch.com/settings/access-keys). Note that access secrets are only available during initial key creation. | 2. Save the file. ### Start your web server and set up a tunnel to handle messages using Node 1. Start the server by executing the following command in your terminal or command prompt: ```shell node index.js ``` 2. Now you need to open a tunnel to the server you just set up. We are using [ngrok](https://ngrok.com/) for this. If you don't have ngrok installed already you can install it with the following command: ```shell npm install ngrok -g ``` 3. Open a new terminal or command prompt and enter: ```shell ngrok http 3000 ``` 4. Copy the HTTP address that ends with .ngrok.io. ### Configure your webhook to handle messages with Node 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](https://community.sinch.com/t5/Conversation-API/How-to-add-a-webhook-to-a-Conversation-API-app/ta-p/8100). Set your webhook URL to the HTTP address you copied in the previous step. Additionally, assign the following triggers: - `CONVERSATION_START` - `CONVERSATION_STOP` - `EVENT_DELIVERY` - `EVENT_INBOUND` - `MESSAGE_DELIVERY` - `MESSAGE_INBOUND` - `UNSUPPORTED` ### Test how the Node application handles incoming messages 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. Java ### Handle incoming messages using Java Note: Before you can get started, you need the following already set up: - - [JDK 21 or later](https://www.oracle.com/java/technologies/downloads/) and a familiarity with how to create a new Java application. (The SDK itself only requires JDK 8 or later, but this quickstart guide uses JDK 21 as it is the latest version with long term support.) - [Apache Maven](https://maven.apache.org/install.html) and a familiarity with how to use the Maven CLI. - [ngrok](https://ngrok.com/). You'll use ngrok to open a tunnel to your local server. To quickly get started setting up a simple client application using the Java SDK: 1. If you haven't already, clone the [sinch-sdk-java](https://github.com/sinch/sinch-sdk-java) repository. 2. Navigate to the `/examples/getting-started/conversation/respond-to-incoming-message/src/main/resources` folder. 3. Your Sinch credentials can be found on the [Access Keys](https://dashboard.sinch.com/settings/access-keys) page of the Sinch Build Dashboard. You can also [create new access key IDs and Secrets](https://community.sinch.com/t5/Conversation-API/How-to-get-your-access-key-for-Conversation-API/ta-p/8120), if required. To add them, open the `application.yaml` file and enter them under the `credentials:` tag: - `project-id:`- project ID - `key-id:` - API key ID - `key-secret:` - API key secret You also need to set the Conversation region under the `conversation:` tag: - `region` - Conversation region (US/EU) ### Start your web server and set up a tunnel to handle incoming messages using Java 1. Navigate to `examples/getting-started/conversation/respond-to-incoming-message` and start the server by executing the following command: ```shell mvn clean spring-boot:run ``` 2. Now you need to open a tunnel to the server you just set up. We are using [ngrok](https://ngrok.com/) for this. If you don't have ngrok installed already, install it with the following command: ```shell npm install ngrok -g ``` 3. Open a terminal or command prompt and enter: ```shell ngrok http 8090 ``` 4. Copy the HTTPS address that ends with **.ngrok.io**. ### Configure your webhook to handle incoming messages using Java 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](https://community.sinch.com/t5/Conversation-API/How-to-add-a-webhook-to-a-Conversation-API-app/ta-p/8100). 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 how the Java application handles incoming messages 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. .NET ### Handle incoming messages using .NET Note: Before you can get started, you need to do the following: - - [The latest version of .Net Core with **Long Term Support**](https://dotnet.microsoft.com/download) and a familiarity with how to create a new MVC application. - [ngrok](https://ngrok.com/). You'll use ngrok to open a tunnel to your local server. 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: ```shell dotnet new mvc ``` 3. Add the `Newtonsoft.Json` NuGet package. ```shell dotnet add package Newtonsoft.Json ``` ### Modify your .NET application to handle incoming messages Note: This tutorial uses basic authentication for testing purposes. We recommend OAuth 2.0 authentication in a production environment. Read more about [authentication methods](/docs/conversation/api-reference/conversation#section/overview/authentication). 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](/docs/conversation/message-types/text-message/) in response. IncomingController.cs // 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 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 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; } } } 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. 1. Assign your values to the following parameters: | Parameter | Your value | | --- | --- | | `Access_Key` | Find your access key on your Sinch [dashboard](https://dashboard.sinch.com/settings/access-keys). | | `Access_Secret` | Find your access secret on your Sinch [dashboard](https://dashboard.sinch.com/settings/access-keys). Note that access secrets are only available during initial key creation. | 2. Save the file. 3. Compile your application by executing the following command: ```shell dotnet build ``` ### Start your web server and set up a tunnel to handle incoming messages using .NET 1. Start the server by executing the following command: ```shell 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](https://ngrok.com/) for this. if you don't have ngrok installed already you can install it with the following command: ```shell npm install ngrok -g ``` 3. Open a terminal or command prompt and enter: ```shell 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 to handle incoming messages using .NET 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](https://community.sinch.com/t5/Conversation-API/How-to-add-a-webhook-to-a-Conversation-API-app/ta-p/8100). 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 how the .NET application handles incoming messages 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. Python ### Handle incoming messages using Python Note: Before you can get started, you need to do the following: - - [Python](https://www.python.org/) and a familiarity with how to create a new file. - [PIP (package installer for Python)](https://pypi.org/project/pip/) and a familiarity with how to install Python modules. - [Flask](https://flask.palletsprojects.com/en/2.0.x/installation/) and a familiarity with how to set up a Flask environment and app. - [ngrok](https://ngrok.com/). You'll use ngrok to open a tunnel to your local server. - [Poetry](https://python-poetry.org/) for dependency management. 1. If you haven't already, clone the [sinch-sdk-python](https://github.com/sinch/sinch-sdk-python) repository. 2. Navigate to the `examples/getting-started/conversation/send_handle_incoming_sms` folder. 3. Copy the example `.env` file by running the following command: Linux/Mac ```bash cp .env.example .env ``` Windows (Command Prompt) ```cmd copy .env.example .env ``` Windows (Powershell) ```powershell Copy-Item .env.example .env ``` 1. Open the `.env` [file](https://github.com/sinch/sinch-sdk-python/blob/main/examples/snippets/.env.example) you just created. Using the [access key credentials](https://dashboard.sinch.com/settings/access-keys) from your Sinch Build Dashboard, populate the following fields with your values: | Field | Description | | --- | --- | | SINCH_PROJECT_ID | The unique ID of your Project. | | SINCH_KEY_ID | The unique ID of your access key. | | SINCH_KEY_SECRET | The secret that goes with your access key. **Note:** For security reasons, this secret is only visible right after access key creation. | | SINCH_CONVERSATION_REGION | The region where your Conversation API app is located, for example, `eu` or `us`. | 1. Save the file. 2. The Python SDK uses [Poetry](https://python-poetry.org/) to manage packages and dependencies, so install those dependencies using the following command: ```cmd poetry install ``` ### Start your web server and set up a tunnel to handle incoming messages using Python 1. Start the server by opening a command prompt or terminal to the `examples/getting-started/conversation/send_handle_incoming_sms` folder and executing the following command: ```shell poetry run python server.py ``` By default, your web server is started on port 3001. 2. Now you need to open a tunnel to the server you just set up. We are using [ngrok](https://ngrok.com/) for this. If you don't have ngrok installed already you can install it with the following command: ```shell npm install ngrok -g ``` 3. Open a terminal or command prompt and enter: ```shell ngrok http 3001 ``` 4. Copy the HTTPS address that ends with .ngrok-free.app. ### Configure your webhook to handle incoming messages using Python In order 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](https://community.sinch.com/t5/Conversation-API/How-to-add-a-webhook-to-a-Conversation-API-app/ta-p/8100). 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 how the Python application handles incoming messages 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.