1. Introduction
This document provides detailed specifications for using the Wire2Air SendMessage API endpoint. This powerful endpoint allows you to send various types of messages, including SMS, MMS, RCS, and WhatsApp, by specifying the message type in the request body.
2. Authentication
All requests to the SendMessage API must be authenticated using an API Key. The key must be included in the request header as appkey.
How to Generate Your API Key
To get your API key, please follow the instructions provided in our help center:
3. API Endpoint Specification
Endpoint
POST /api/Message
Request Headers
| Header | Value | Required |
|---|---|---|
apikey |
YOUR_API_KEY |
Yes |
Content-Type |
application/json |
Yes |
4. Request Body
The request body is a JSON object containing the details of the message to be sent. The library field is crucial as it determines the type of message.
Common Fields
| Field | Type | Required | Description |
|---|---|---|---|
from |
String | Yes | Your registered sending number (e.g., "16074633530"). |
to |
String | Yes | The recipient's phone number (e.g., "12129204690"). |
library |
String | Yes | The message type. Must be one of: SMS, MMS, RCS, WhatsApp. |
text |
String | Varies | The text content of the message. Required for SMS/MMS and plain text RCS. |
replyPath |
String | No | A specific webhook URL to receive replies for this message, overriding the account's default webhook. |
5. Message Types & Examples
5.1. Send a Text Message (SMS)
To send a standard text message, set the library field to "SMS".
Request Body
{
"from": "16074633530",
"to": "12121110000",
"text": "This is a test message from Wire2Air.",
"library": "SMS"
}
5.2. Send an MMS Message
To send a multimedia message, set library to "MMS" and include the baseUrl and attachments fields.
Request Body
{
"from": "16074633530",
"to": "12121110000",
"text": "Check out this new image!",
"library": "MMS",
"baseUrl": "https://cloud.yourserver.com/media/",
"attachments": [
"https://cloud.yourserver.com/media/image1.jpg"
]
}
5.3. Send an RCS Plain Text Message
To send a simple text-only message over the RCS channel, set library to "RCS" and provide the text field.
Request Body
{
"from": "16074633530",
"to": "12121110000",
"text": "This is a plain text RCS message.",
"library": "RCS"
}
5.4. Send an RCS Rich Card Message
To send a rich message with a card layout, set library to "RCS" and provide the rcsDataDto object.
Request Body
{
"from": "16074633530",
"to": "12121110000",
"library": "RCS",
"rcsDataDto": {
"text": "Explore our new offers!",
"title": "Summer Sale",
"description": "Get 50% off on all items. Tap to learn more.",
"imageUrl": "https://cdn.yourserver.com/images/summer-sale.png",
"suggestions": [
{ "type": "REPLY", "text": "Shop Now" },
{ "type": "OPEN_URL", "text": "Visit Website", "url": "https://www.yourwebsite.com" }
]
}
}
5.5. Send an RCS Rich Media Message
To send a standalone rich media file, use the fileUrl field within the rcsDataDto payload.
Request Body
{
"from": "16074633530",
"to": "12121110000",
"library": "RCS",
"rcsDataDto": {
"text": "Here is the product demo you requested.",
"fileUrl": "https://cdn.yourserver.com/videos/product-demo.mp4",
"thumbnailUrl": "https://cdn.yourserver.com/images/video-thumbnail.png",
"suggestions": [
{ "type": "REPLY", "text": "Thanks!" }
]
}
}
5.6. Send a WhatsApp Message
To send a WhatsApp message using a pre-approved template, set library to "WhatsApp" and provide the whatsAppMessageDto.
Request Body
{
"from": "16074633530",
"to": "12121110000",
"library": "WhatsApp",
"whatsAppMessageDto": {
"templateName": "order_confirmation",
"language": "en_US",
"templateData": {
"body": {
"placeholders": ["John Doe", "AB-12345"]
}
}
}
}
6. Response Handling
Success Response
A successful request will return a 200 OK status and a JSON body indicating the message has been queued.
{
"Response": "Message Queued successfully",
"Type": "Out",
"Id": "c904c42073be4cb39da50f46c97c11ec"
}
Error Response
If the request fails, the API will return an appropriate 4xx or 5xx status code with an error description.
7. Receiving Messages (Webhook)
To receive inbound messages, you must configure a webhook. Our platform will POST incoming message data to your specified URL. You can set a default webhook at the account level or provide a message-specific webhook using the replyPath parameter.
For complete instructions on setting up and handling webhooks, please refer to our documentation:
Appendix: DTO Schemas
The following sections provide the full data structures for complex objects used in API requests.
RCSDataDto
{
"type": "string",
"orientation": "string",
"alignment": "string",
"height": "string",
"imageUrl": "string",
"title": "string",
"description": "string",
"text": "string",
"fileUrl": "string",
"thumbnailUrl": "string",
"card_width": "string",
"items": [
{
"height": "string",
"mediaUrl": "string",
"title": "string",
"description": "string",
"suggestions": [
{
"type": "string",
"text": "string",
"phoneNumber": "string",
"postback": "string",
"url": "string"
}
]
}
],
"suggestions": [
{
"type": "string",
"text": "string",
"phoneNumber": "string",
"postback": "string",
"url": "string"
}
]
}
WhatsAppMessageDto
{
"templateName": "string",
"language": "string",
"templateData": {
"body": {
"placeholders": [ "string" ]
},
"header": {
"type": "string",
"text": "string",
"mediaUrl": "string",
"filename": "string"
},
"buttons": [
{
"type": "string",
"parameter": "string"
}
]
},
"callbackData": "string",
"smsFailover": {
"sender": "string",
"text": "string",
"validityPeriod": {
"amount": 0,
"timeUnit": "string"
}
}
}