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

Step 1

Launch the wizard

Step 2

Send another message

Step 3

Handle incoming messages

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:

Once you have created an account and logged in, the Get started with SMS onboarding wizard becomes available. To launch the wizard, select SMS from the left menu. Click Get started and progress through the Get started with SMS onboarding wizard.

This wizard will automatically:

• Create a Conversation API app with a configured SMS channel, which allows you to send SMS messages using Conversation API.
• Assign a free test number to your account and corresponding SMS channel.
• Walk you through the process of creating an access key and access key secret, both of which are required for authenticating with Conversation API. You must securely record the access key secret at the time of access key creation. The secret for that access key will not be displayed again.
• Help you send your very first SMS message via Conversation API! If you encounter any issues, see the Troubleshooting section.

Congratulations! If you completed 1. Launch the Get started with SMS wizard, you've already sent your first message using Conversation API. Now you can try building your own app to send SMS messages using Conversation API.

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!):

{
  "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"
  }
}

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 earlier in this guide), process the message, and send the contents of the message back to your phone:

{
  "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\" }"
}

If you encounter issues when using the wizard, note that the region assigned to your Conversation API app and SMS channel must match in order for the Conversation API app and SMS channel to function together correctly.

You can view your Conversation API app's region assignment on the Conversation apps page and you can view your SMS channel's region assignment (which should match the Conversation API app's region assignment) by navigating to the SMS Channels page and clicking on the relevant SMS channel (when onboarding, there should be only one SMS channel available).

If the regions don't match:

1. Exit the wizard.
2. If you haven't already, find and record your project ID.
3. If you don't already, ensure you have your access key ID and access key secret available.
4. Disconnect your existing SMS channel from its currently assigned Conversation API app.
5. Create a new Conversation API app in a region that matches your SMS channel's region. Record your Conversation API app's ID value.
6. Connect your existing SMS channel to the newly created Conversation API app.
7. Proceed to 2. Send another message.