<!-- BusyBot node reference — https://busybot.net/tools/vonage/ -->

> Node: Vonage (`vonage`) · Action · v1
> Category: Communication · Credentials: Vonage API (`vonageApi`)
> Updated: 2026-08-16

# Vonage

> Send SMS text messages via the Vonage (Nexmo) API.

## Overview

Vonage (formerly Nexmo) is a cloud communications platform. This tool sends SMS text messages using the Vonage REST API. Authentication uses an API key and secret which are sent as form-encoded fields in the request body to https://rest.nexmo.com/sms/json. The API returns a messages array; each element represents one SMS part (long messages may be split into multiple parts). Supports additional fields like callback URL, client reference, message class, TTL, and delivery receipts.

**Category:** Communication  
**Tool Name:** `vonage`  
**Version:** 1

**Appearance:** Icon: `lucide-Phone` | Color: `#FFFFFF`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Vonage API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/vonage-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| SMS | `sms` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Send | `send` | Send an SMS message |

### Parameters

#### SMS: Send

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| From | `string` | Yes | — | The name or number the message should be sent from. Can be an alphanumeric sender ID (up to 11 characters) or a phone number in E.164 format. Supports expressions. |
| To | `string` | Yes | — | The recipient phone number in E.164 format (e.g. 14155552671). Supports expressions. |
| Message | `string` | Yes | — | The body of the message being sent. Supports expressions like {{ $json.body }}. |
| Additional Fields | `collection` | No | `{}` | Optional extra values sent with the message. |
| — Account Ref | `string` | No | — | An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, contact support@nexmo.com. |
| — Callback | `string` | No | — | The webhook endpoint the delivery receipt for this SMS is sent to. This parameter overrides the webhook endpoint set in the Vonage Dashboard. |
| — Client Ref | `string` | No | — | You can optionally include your own reference of up to 40 characters. |
| — Message Class | `options` | No | — | The Data Coding Scheme value of the message. |
| | | | | Options: `0`, `1`, `2`, `3` |
| — Protocol ID | `string` | No | — | The value of the protocol identifier to use. Ensure that the value is aligned with udh. |
| — Status Report Req | `boolean` | No | `false` | Whether to receive a Delivery Receipt. |
| — TTL (in Minutes) | `number` | No | `4320` | By default Vonage attempts delivery for 72 hours (4320 minutes). The API expects milliseconds; this value is automatically converted. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The Vonage response is merged onto the top level of the item JSON; anything already on the item passes through, and binary data is forwarded unchanged.

Vonage splits long messages into parts and returns one entry per part:

- **Single-part message** — the fields of that one message entry land directly on the item: the message ID, its `status`, the price charged and the remaining account balance.
- **Multi-part message** — the item instead carries `message-count` and a `messages` array holding every part.

A part is only treated as delivered when its `status` is `"0"`. Any other status fails the item with the accompanying `error-text`, so a rejected send routes to the Error port (or halts the run) rather than passing through silently.

## Usage Examples

- Send an SMS notification to a customer when their order ships
- Send a verification code to a phone number via SMS
- Send an alert SMS to an on-call engineer when a monitor triggers
- Send bulk SMS messages to a list of phone numbers from a database
- Send an SMS with a delivery receipt callback for tracking

## Example Configuration

Send a basic SMS from an alphanumeric sender ID:

```json
{
  "type": "vonage",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "from": "MyCompany",
    "to": "+14155552671",
    "message": "Hello! This is a test message from MyCompany."
  }
}
```

Send from a phone number instead of a sender ID:

```json
{
  "type": "vonage",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "from": "+14155551234",
    "to": "+14155552671",
    "message": "Your order has been confirmed and will be delivered tomorrow."
  }
}
```

Request a delivery receipt and shorten the delivery window:

```json
{
  "type": "vonage",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "from": "AlertSystem",
    "to": "+14155552671",
    "message": "Alert: Your account balance is low.",
    "additionalFields": {
      "client-ref": "alert-001",
      "status-report-req": true,
      "callback": "https://myapp.com/webhooks/sms-status",
      "ttl": 1440
    }
  }
}
```

Send one message per incoming item, with the recipient taken from the item and concurrency held down for bulk runs:

```json
{
  "type": "vonage",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "maxConcurrency": 5,
    "from": "BulkSender",
    "to": "{{ $json.phone }}",
    "message": "Limited rate bulk message",
    "additionalFields": {
      "account-ref": "bulk-campaign",
      "client-ref": "{{ $json.id }}"
    }
  }
}
```

Send a short-lived verification code:

```json
{
  "type": "vonage",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "from": "AuthCode",
    "to": "{{ $json.phone }}",
    "message": "Your verification code is: {{ $json.code }}. This code expires in 10 minutes.",
    "additionalFields": {
      "client-ref": "2fa-verification",
      "status-report-req": true,
      "ttl": 10
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Vonage sends SMS text messages via the Nexmo REST API. Use it to send notifications, alerts, or verification codes to phone numbers.