# Sinch Exit API

If you already have an integration using the Sinch SMS API to send and receive SMS messages (basic send and receive only), you can use this guide to start sending your SMS messages through Bird without having to rewrite your API integration.

The Bird Sinch Exit API allows you to send SMS messages through the Bird Engagement Platform, using your existing Sinch Integration. It acts as an adapter that translates the requests and responses from the Sinch format to Bird format and vice versa.

## How does it work?

Your Sinch integration will send the request using the Sinch API format to the Bird Sinch Exit API. Our API will accept the Sinch formatted request, translate it to Bird's format, process the message, and then translate our response to the Sinch API response format you're expecting, ta-da! You don't have to rewrite all of your integration to start sending messages via Bird.

## Setup the integration

1. Setup your Bird Engagement Platform account
2. Install an SMS channel
3. Copy your main keys
4. Update your Sinch integration URL and keys
5. Setup your Webhook to receive events and incoming messages

### Setup your Bird account

Login to your Bird Engagement Platform account or [Sign up](https://app.messagebird.com/auth/sign-up) for a new account if you don't have one.

### Install an SMS channel

You will need to install an SMS channel on a working phone number. Follow this guide on how to [install an SMS channel](https://docs.messagebird.com/applications/enable-channels/sms/install-sms).

### Copy your main keys

#### You will need:

* Your [workspace ID](https://docs.messagebird.com/applications/general/organization-settings/how-to-find-a-workspace-id) (click **Edit workspace** to see your ID)
* [Access key](https://app.messagebird.com/settings/access-keys)
* The phone number of the SMS channel you're sending messages from

### Update your Sinch Integration

Now that you have all the keys you need, you will need to do minimal change to your existing Sinch integration. 

1. Update the domain name from **https\://\[us|eu|au|br|ca].sms.api.sinch.com** to one of the following domains:
   * EU (for Europe region): `https://eu-west-1.sinch.to.api.bird.com`
   * US (for US region): `https://us-west-1.sinch.to.api.bird.com`
2. Update your **service\_plan\_id** to use your Bird **WorkspaceID**
3. Update your **Token** to use your Bird **AccessKey**
4. Update the “**From**” number to the phone number you used to setup the SMS channel on our end

That's it! You're ready to start sending SMS messages via Bird.

### Setup a Webhook subscription

Setting up a webhook subscription can currently be done via the API using the following endpoint:

{% openapi src="<https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FQ8gpihs9epXmbMZgHjmT%2FSMS-Webhook-twilio-2.yml?alt=media&token=1bce1175-4759-4cb7-84c1-c2bed4f949b4>" path="/organizations/{organization\_id}/workspaces/{workspace\_id}/webhook-subscription" method="post" %}
[SMS-Webhook-twilio-2.yml](https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FQ8gpihs9epXmbMZgHjmT%2FSMS-Webhook-twilio-2.yml?alt=media\&token=1bce1175-4759-4cb7-84c1-c2bed4f949b4)
{% endopenapi %}

Here is an example of such a request

<pre class="language-json"><code class="lang-json">{
<strong>    "service": "channels",
</strong>    "event": "sms.inbound",
<strong>    "eventFilters": [{
</strong>        "key": "channelId",
        "value": "{{channel_id}}"
    }],
    "template": "sinch",
    "url": "https://your.site/webhook/url",
    "signingKey": "your-secret-signing-key"
}
</code></pre>

Bird webhooks are signed using the `SigningKey` specified when creating your webhook subscription.

{% hint style="warning" %}
Make sure you keep your SigningKey safe, as it's used to verify the authenticity of the webhook requests.
{% endhint %}

Full webhooks API documentation can be found [here](https://docs.messagebird.com/api/notifications-api/api-reference/webhooks).

#### Setup a Webhook subscription to receive incoming messages

Setting up a webhook subscription is an optional step and is only needed if you need to receive inbound messages (2-way messaging use case). Much like Sinch, Bird's webhooks are set up by channel instance. So, for SMS, webhooks are set up by number.

To receive webhooks for incoming SMS messages on your SMS channel, you need to set up a webhook subscription by using the above request. For incoming messages, set the event to `sms.inbound`. You can choose to receive this webhook in the Sinch format by setting the template parameter to `sinch`.

#### Setup webhook subscription for status reports for outbound messages

You can also set up webhooks for status reports for outbound messages by using the `sms.outbound` event. This is required to make webhooks work for outbound messages since we need a signing key to sign the request.

When you use `callback_url` to subscribe to webhooks for outgoing messages, this URL overwrites the default URL set in the above request and sets the template to use the `sinch` template, regardless of the subscription settings.

Bird also employs a secure way of signing requests. When using the `sinch` template, we will sign our requests the Bird way, with the Bird header.<br>

## Sinch Exit API Explained

Our Sinch Exit API translates requests using the Sinch format to the Bird format, before sending it to the Bird API. And on receiving a response from our API, it translates it back into the Sinch format. This section explains which endpoints are supported and how we translate and map fields between both APIs.

### Endpoints

Currently, the Sinch Exit API is limited to sending SMS messages exclusively through your Sinch Integration. The supported endpoints are:

<table><thead><tr><th width="171">Operation</th><th>Endpoint</th></tr></thead><tbody><tr><td>Send message</td><td><code>POST /xms/v1/{{workspaceID}}/batches</code></td></tr><tr><td>Fetch message</td><td><code>GET /xms/v1/{{workspaceID}}/batches/{{messageID}}</code></td></tr><tr><td>List messages</td><td><code>GET /xms/v1/{{workspaceID}}/batches</code></td></tr></tbody></table>

### Message response

The message object's response resembles Sinch's, though some fields may be empty. Below is an example of our responses:

<table data-full-width="true"><thead><tr><th width="211">JSON field</th><th width="198">Status</th><th width="240">Bird field</th><th>Example</th></tr></thead><tbody><tr><td><code>id</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td><td><code>id</code></td><td><code>"id":""</code></td></tr><tr><td><code>to</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td><td><p><code>receiver.contacts[].</code></p><p><code>identifierValue</code></p></td><td><code>"to":["+31623456789"]</code></td></tr><tr><td><code>from</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td><td><code>sender.connector.identifierValue</code></td><td><code>"from": "+1234567890"</code></td></tr><tr><td><code>body</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td><td><code>body.text.text</code></td><td><code>"body": "Hello World!"</code></td></tr><tr><td><code>type</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e1">🟡</span> Always <code>mt_text</code></td><td>-</td><td><code>"type": "mt_text"</code></td></tr><tr><td><code>canceled</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e1">🟡</span> Always <code>false</code></td><td>-</td><td><code>"canceled": false</code></td></tr><tr><td><code>delivery_report</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e1">🟡</span> Always <code>none</code></td><td>-</td><td><code>"delivery_report": "none"</code></td></tr><tr><td><code>client_reference</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td><td><code>reference</code></td><td><code>"client_reference": "abcdef"</code></td></tr><tr><td><code>created_at</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td><td><code>createdAt</code></td><td><code>"created_at": "YYYY-MM-DDThh:mm:ss.SSSZ"</code></td></tr><tr><td><code>modified_at</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td><td><code>updatedAt</code></td><td><code>"modified_at": "YYYY-MM-DDThh:mm:ss.SSSZ"</code></td></tr><tr><td><code>expire_at</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td><td>-</td><td><code>"expired_at":""</code></td></tr></tbody></table>

### Create message

<table><thead><tr><th width="347">Form field</th><th>Status</th></tr></thead><tbody><tr><td><code>service_plan_id</code> (Path)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Use your Bird <code>WorkspaceID</code></td></tr><tr><td><code>to[]</code> (Required)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Supported, only the first item will be used to send to</td></tr><tr><td><code>from</code> (Required)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported. Must be the number of an active SMS channel in MessageBird.</td></tr><tr><td><code>body</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td></tr><tr><td><code>delivery_report</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Always <code>per_recipient</code> if used</td></tr><tr><td><code>callback_url</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td></tr><tr><td><code>client_reference</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td></tr><tr><td><code>parameters</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Ignored if used</td></tr><tr><td><code>type</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Always <code>mt_text</code></td></tr><tr><td><code>sent_at</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Ignored if used, scheduling not supported</td></tr><tr><td><code>expire_at</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Ignored if used, validity not supported</td></tr><tr><td><code>feedback_enabled</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Ignored if used</td></tr><tr><td><code>flash_message</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Ignored if used</td></tr><tr><td><code>truncate_concat</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Ignored if used</td></tr><tr><td><code>max_number_of_message_parts</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Ignored if used</td></tr><tr><td><code>from_ton</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Ignored if used</td></tr><tr><td><code>from_npi</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e0">🟠</span> Ignored if used</td></tr></tbody></table>

#### Response

See [message response](#message-responses).

### List messages

#### Request

Filtering messages can be done using the following query string parameters:

<table><thead><tr><th width="268">Query parameter</th><th>Status</th></tr></thead><tbody><tr><td><code>service_plan_id</code> (Path)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Use your Bird <code>WorkspaceID</code></td></tr><tr><td><code>page</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f534">🔴</span> Not Supported</td></tr><tr><td><code>page_size</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e1">🟡</span> Supported, but with a maximum of 100</td></tr><tr><td><code>from</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td></tr><tr><td><code>start_date</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td></tr><tr><td><code>end_date</code> (Optional)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td></tr></tbody></table>

#### Response

<table><thead><tr><th width="269">JSON response</th><th>Channels field</th></tr></thead><tbody><tr><td><code>page</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td></tr><tr><td><code>page_size</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td></tr><tr><td><code>count</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported</td></tr><tr><td><code>batches</code></td><td><span data-gb-custom-inline data-tag="emoji" data-code="1f7e2">🟢</span> Supported: See message response</td></tr></tbody></table>