# SMS/MMS

With VoIP Number [API SDK](https://www.npmjs.com/package/voipnumber) you can send SMS to any number in the world programmatically, straight from your app. Simply follow these steps

## Install API SDK   

```javascript
npm i voipnumber
```

## Send SMS

{% tabs %}
{% tab title="Nodejs" %}

```javascript
const voipnumber = require('voipnumber')('accountId','apiToken');

const from = '+447445459147';
const to = '+447483866525';

voipnumber.sms.send(from, to, 'Thank you').then((res) => {
    console.log(res);
}).catch((err) => {
    console.log(err);
});
```

{% endtab %}

{% tab title="Output" %}

```
{
  status: 'OK',
  result: {
    status: 'OK',
    result: {
      status: 'queued',
      body: 'Thank you',
      timestamp_s: 1716193717,
      created: '20 May 2024 08:28:37',
      id: 'feefcc83-d6ae-4580-b4dc-6ee16b37ff04'
    }
  }
}
```

{% endtab %}
{% endtabs %}

First number (`from`) must belong to your account on [VoIP Number](https://app.voipnumber.net/dashboard) and must have SMS capabilities. You will find your `accountId` and `apiToken` on the Settings page at [app.voipnumber.net/settings](https://app.voipnumber.net/settings)

<figure><img src="/files/okKG8kYWhs9fHNIzd20H" alt=""><figcaption><p>Credentials for your API SDK access</p></figcaption></figure>

You can change your API token anytime by clicking `GENERATE`

### Response to Send SMS request

{% tabs %}
{% tab title="Success" %}

```json
{
  status: 'OK',
  result: {
    status: 'OK',
    result: {
      status: 'queued',
      body: 'Thank you',
      timestamp_s: 1716193717,
      created: '20 May 2024 08:28:37',
      id: 'feefcc83-d6ae-4580-b4dc-6ee16b37ff04'
    }
  }
}
```

{% endtab %}

{% tab title="Error" %}

```json
{
  status: 'Error',
  result: { error_code: 'USER_NOT_FOUND', error: 'User not found' }
}
```

{% endtab %}
{% endtabs %}

On success response contains&#x20;

* `status`: will be set to `queued` , you will see when it changes to `delivered` on your Messaging page at app.voipnumber.net/messaging
* `body`: text sent in the SMS
* `timestamp_s`: number of seconds which have passed since UNIX epoch (1 January 1970)
* `created`: same timestamp but in human-readable format
* `id`: the reference to the SMS that you will also find on Messaging Data Records page on your account at [app.voipnumber.net/messaging](https://app.voipnumber.net/messaging)

On error, an error code and error description is returned. These are possible values

<table><thead><tr><th>Error code</th><th>Description</th></tr></thead><tbody><tr><td><pre><code>USER_ACCOUNT_MISSING
</code></pre></td><td>AccountId not set or empty</td></tr><tr><td><pre><code>API_TOKEN_MISSING
</code></pre></td><td>API token not set or empty</td></tr><tr><td><pre><code>USER_NOT_FOUND
</code></pre></td><td>User with this AccountId cannot be found</td></tr><tr><td><pre><code>API_TOKEN_INVALID
</code></pre></td><td>API token doesn't match AccountId</td></tr><tr><td><pre><code>NUMBER_NOT_FOUND
</code></pre></td><td>Number doesn't exist on VoIP Number</td></tr><tr><td><pre><code>NUMBER_OWNERSHIP
</code></pre></td><td>Number doesn't belong to this account</td></tr><tr><td><pre><code>MESSAGE_INVALID
</code></pre></td><td>Coding syntax error</td></tr></tbody></table>

<figure><img src="/files/L4iYlyWePr5slL889KzB" alt=""><figcaption><p>SMS logs</p></figcaption></figure>

## Receive SMS

A number with SMS capability can send and receive SMS. To receive an SMS sent to your Number configure a webhook for that Number at [app.voipnumber.net/numbers](https://app.voipnumber.net/numbers)

<figure><img src="/files/ynYmcgfLwzA2gVdAOZ70" alt=""><figcaption></figcaption></figure>

Make sure the url you will set can receive a call from public network. Our message is sent to your webhook from `api.voipnumber.net` in JSON format and contains `Host: 'api.voipnumber.net'` header that you can use for authorization check

```
headers: {
    'Content-Type': 'application/json',
    Host: 'api.voipnumber.net',
    'X-Forwarded-Port': '443',
    'X-Forwarded-Proto': 'https'
},
```

Our message to your webhook contains following data

```
{
      status: 'received',
      from: '+447445459147',
      to: '+447476553275',
      type: 'sms' | 'mms',
      body: 'text sent in SMS',
      mdr_timestamp_s: 1716204585,
      mdr_created: '20 May 2024 11:29:45',
      mdr_id: 'da84a7b1-1a80-4e96-885e-e719d5ec909c'
}
```

where `mdr_timestamp_s`, `mdr_created` and `mdr_id` refer to the `Messaging Data Record` created on receipt of this `SMS/MMS` message. Every SMS/MMS message is reported on the Messaging Data Records page at [app.voipnumber.net/messaging](https://app.voipnumber.net/messaging) ([SMS/MMS](/reporting/sms-mms.md)). You will also see there if your webhook was called and what was the (HTTPs) status code returned by your infrastructure through that call

<figure><img src="/files/BcXpudcmqcGGVsFkvWHE" alt=""><figcaption><p>Inbound SMS logs</p></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.voipnumber.net/api-reference/sms-mms.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.