Vonage Messages integration

What it does

The Vonage Messages integration lets your agency drive a client's SMS program from inside a workflow. Connect a client's Vonage API key and secret once and your workflows can send SMS to one recipient at a time, search messages by id or by date, watch the prepaid account balance, look up outbound SMS pricing for any country, and react in real time when Vonage posts an inbound message or a delivery-receipt update to the configured webhook URL.

Connect a Vonage account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose Vonage Messages and click Connect.
3. In a new tab, sign in to the Vonage Dashboard as the client (or as your agency, if the client has delegated credentials to you).
4. Open Settings, then API settings, and copy the API key and API secret.
5. Paste both values into TaskJuice and save the connection.

To rotate the secret, return to the API settings page, click Change API secret, copy the new value, and update the TaskJuice connection.

Triggers

• vonage-sms/incoming-sms fires when an inbound SMS arrives on a Vonage number you have routed to the workflow. One POST equals one inbound message, and the activation payload carries the message id, sender number, recipient, body, keyword, and timestamp.
• vonage-sms/delivery-receipt fires when Vonage reports a delivery-status change for an outbound SMS (delivered, expired, failed, rejected, accepted, buffered, unknown). The activation payload carries the message id, recipient, status, network code, price, client reference, and timestamp.

Each trigger publishes an inbound URL. Paste it into Vonage under Settings, SMS settings (or attach it to the number under Numbers, Your numbers, Edit), and add a custom header named X-TaskJuice-Inbound-Secret set to a shared secret you also paste into the TaskJuice trigger. Vonage sends that exact value on every POST and TaskJuice verifies it before activating the workflow.

Actions

• vonage-sms/send-sms sends an SMS to a single recipient through the REST SMS API with optional client reference, delivery-receipt URL, message type, TTL, and status-report flag.
• vonage-sms/search-message retrieves a single inbound or outbound SMS by its Vonage message id, including the final delivery status and per-message price.
• vonage-sms/search-messages lists messages sent or received on a specific date, optionally filtered by destination number.
• vonage-sms/get-balance retrieves the account's current prepaid credit balance in EUR.
• vonage-sms/get-pricing retrieves Vonage's outbound SMS pricing for a specific country by ISO 3166-1 alpha-2 code, including per-network breakouts.

Known limitations

• The integration uses Vonage's legacy SMS REST API at rest.nexmo.com. The newer Messages API at api.nexmo.com/v1/messages (which supports WhatsApp, MMS, and Facebook Messenger alongside SMS) will land in a follow-up bundle.
• Outbound auth uses HTTP Basic with the API key as the username and the API secret as the password. Both values must remain server-side; treat a leaked secret the same way you would treat a leaked Bearer token and rotate it from the Vonage Dashboard.
• Inbound webhook verification uses a long-lived shared secret on a custom header (X-TaskJuice-Inbound-Secret). Vonage's newer JWT signing on the Messages API is not used by this integration; rotate the shared secret on a regular cadence.
• Alphanumeric sender IDs are not supported in every country (notably the United States and Canada). Vonage rejects the call with a non-zero status in the response body when the recipient's country forbids the chosen sender; the action surfaces it as a validation error.
• Message history is retained by Vonage for three months. Searches against an older date return an empty result rather than an error.
• The legacy SMS API sends one recipient per request. To fan out to many recipients, drive send-sms from a loop over your recipient list.