# Setup Guide for Bandwidth SMS

This guide describes how to configure Bandwidth SMS for Acrobits Linkup Messaging.

---

## 1. Bandwidth Application Setup

1. Log in to your Bandwidth account.
2. Create a new application and give it a meaningful name.
3. Bandwidth assigns the Application ID automatically.

![Bandwidth application setup](attachments/bandwidth-application-setup.png)

---

## 2. API Credentials Creation

1. Click **API Credentials**.
2. Generate new credentials to get the API token and API secret.
3. Save the secret immediately. Bandwidth will not show it again.

![Bandwidth API credentials](attachments/bandwidth-api-credentials.png)

---

## 3. Configure Callback URLs

1. Enable **Use multiple callback URLs**.
2. Provide both callback URLs:

   **Inbound Callback URL**

   ```text
   https://api-us.messaging.acrobits.cz/bandwidth/callbacks/{bandwidthApplicationId}/incoming-message
   ```

   **Status Callback URL**

   ```text
   https://api-us.messaging.acrobits.cz/bandwidth/callbacks/{bandwidthApplicationId}/message-status-update
   ```

3. Replace `{bandwidthApplicationId}` with the real Application ID from the Bandwidth dashboard.
4. Enable username/password authentication for both callbacks.
5. Use the same callback user ID for the inbound and status callbacks.
6. Use the same callback password for the inbound and status callbacks.

---

## 4. Location Setup

1. Create a new Location in Bandwidth.
2. On the **Messaging** tab, enable **SMS** using the HTTP API, Version 2.
3. Choose the appropriate geographic reach, for example Zone 1 for the United States or Zone 5 for Europe.
4. Associate at least one phone number per user. These numbers are used for sending and receiving SMS.

![Bandwidth location messaging settings](attachments/bandwidth-location-messaging.png)

---

## 5. Associate the Location with the Application

Return to the application settings and associate the newly created Location with the Bandwidth application.

![Bandwidth associated location](attachments/bandwidth-associated-location.png)

---

## 6. Gather Required Credentials

Collect the following values:

- Bandwidth API token and API secret
- Callback user ID and password
- Bandwidth account ID
- Bandwidth Application ID

---

## 7. Prepare Test Accounts

Create Netsapiens test accounts, or provide existing accounts that Acrobits can use for testing.

---

## 8. Assign SMS Numbers to Test Accounts

Assign the newly allocated SMS numbers to the test accounts in the Metaswitch or Netsapiens portal.

If the test Metaswitch or Netsapiens accounts already have SMS numbers assigned, go to the Bandwidth dashboard and add those SMS numbers to the Location of the test Bandwidth application.