Sending Messages

Send personalized messages across SMS, WhatsApp, Telegram and Signal using your message templates and configured providers.

Single Message Sending

Send a message to a single recipient. The preferredProvider field lets you choose which channel to use for this specific send.

POST /message/send
Content-Type: application/json
x-api-key: {your-api-key}

{
  "templateId": "message-template-uuid",
  "to": "+1234567890",
  "preferredProvider": "twilio",
  "variables": {
    "firstName": "John",
    "code": "123456"
  }
}

When using JWT authentication instead of an API key, include projectId in the request body.

Response:

{
  "message": "Message sent successfully",
  "messageId": "msg-id"
}

Recipient Format by Provider

The to field format depends on the provider being used:

Provider	Format	Example
twilio, termii, sns, infobip	Phone number with country code	+2348012345678
whatsapp, whatsapp_twilio, signal	Phone number with country code	+12125551234
telegram	Telegram Chat ID	123456789
messagepipe	Phone number with country code	+2348012345678

Bulk Message Sending

Send the same message to multiple recipients:

POST /message/send-bulk
Content-Type: application/json
x-api-key: {your-api-key}

{
  "templateId": "message-template-uuid",
  "preferredProvider": "whatsapp",
  "recipients": [
    "+1234567890",
    "+1234567891"
  ],
  "variables": {
    "eventName": "Flash Sale",
    "discount": "50%",
    "expiryTime": "6 PM today"
  }
}

Response:

{
  "message": "Bulk message operation completed",
  "success": true,
  "results": [
    {
      "recipient": "+1234567890",
      "success": true,
      "messageId": "msg-id-1",
      "provider": "whatsapp",
      "deliveryLogId": "delivery-log-uuid"
    },
    {
      "recipient": "+1234567891",
      "success": true,
      "messageId": "msg-id-2",
      "provider": "whatsapp",
      "deliveryLogId": "delivery-log-uuid"
    }
  ]
}

Available Providers

The preferredProvider field accepts one of the following values:

Value	Channel	Notes
messagepipe	SMS	Built-in provider, no config required
twilio	SMS	Requires Twilio account credentials
termii	SMS	Optimized for African markets
sns	SMS	AWS SNS
infobip	SMS	Global coverage
whatsapp	WhatsApp	Via Meta's Business API
whatsapp_twilio	WhatsApp	WhatsApp via Twilio
telegram	Telegram	Via Telegram Bot API
signal	Signal	Via self-hosted Signal CLI

Required Fields

• templateId: UUID of the message template to use
• preferredProvider: The provider/channel to use for this send request
• to / recipients: Recipient identifier(s). The format depends on the provider being used
• variables: Object containing template variable values

Error Handling

Template Not Found

{
  "error": "Message template not found",
  "statusCode": 404
}

Invalid Request

{
  "error": "Invalid template or missing project ID",
  "statusCode": 400
}

Provider Failure

{
  "message": "All providers failed: provider specific error",
  "error": "Internal Server Error",
  "statusCode": 500
}

Provider Failover

Even when a preferredProvider is specified, MessagePipe uses the priority-based failover system as a safety net. If your preferred provider fails, the system automatically falls back to the next available configured provider in your project.

To control the failover order, configure provider priorities in your Message Config.