Add Message
Add Messages to the queue to be sent.
TIP
We suggest using the add-message endpoint as the preferred method for sending messages
Supported features
- Multi channel support
- Sending via Shared inbound-enabled Sender IDs
- Sending multiple unique messages in the same request
Request
Endpoint
Messaging Plus expects a POST request
https://mplus.instagiv.com/messageQuery strings
| Key | Required | Description | Example |
|---|---|---|---|
key | true | Account API key | ?key=aaaabbbbcccc111222333 |
isDryrun | false | Whether these messages should be processed in 'dryrun' mode. Dryrun messages are not added to the queue. Defaults to false | ?dryRun=true |
Body
// Sending a single message
{
"messages": [
{
"from": {
"type": "custom",
"value": "sender-id"
},
"to": "441111111111",
"body": "This is a test message!"
}
]
}// Showing usage of all available parameters
{
"messages": [
{
"from": {
"type": "custom",
"value": "sender-id"
},
"to": "441111111111",
"body": "This is a test message!",
"callback": "https://my-callback.com/delivery-receipt",
"channels": ["sms"],
"id": "b2693dfe-0813-427a-bc2f-62b0e9292403",
"send_at": "2026-01-01T09:00:00Z"
}
]
}// Sending multiple messages
{
"messages": [
{
"from": {
"type": "custom",
"value": "sender-id-1"
},
"to": "441111111111",
"body": "This is my first test message!"
},
{
"from": {
"type": "custom",
"value": "sender-id-2"
},
"to": "442222222222",
"body": "This is my second test message!"
}
]
}// Specifying message defaults
{
"defaults": {
"from": {
"type": "custom",
"value": "sender-id"
}
},
"messages": [
{
"to": "441111111111",
"body": "This is the first test message!",
},
{
"to": "442222222222",
"body": "This is the second test message!",
},
]
}This example shows the minimum required to send a message
Body parameters
| Key | Required | Expected value | Description |
|---|---|---|---|
messages | true | Message[] | List of messages to be sent |
defaults | false | Message | Default message to override messages with |
Message Object
| Key | Required | Expected value | Description |
|---|---|---|---|
to | true | string | Destination mobile number |
from.type | true | "custom"|"shared" | Type of sender ID being specified |
from.value | conditional | string | Sender ID |
body | true | string | Body content to send in message |
callback | false | string | URL to send webhook/callback delivery receipts to |
channels | false | string[] | Priority ordered list of message channels to try sending via. Available channels |
id | false | string | UUID string identifier for the message |
send_at | false | string | ISO 8601 formatted timestamp, representing when to send this message. Expects a timestamp >5 minutes into the future. GMT timezone |
Response
Body
{
"messages": [
{
"to": "441111111111",
"body": "This is a test message!",
"from": {
"type": "custom",
"value": "mplus-test"
},
"batchUuid": "c4ae0c8a-bbb2-4ce3-8ebc-5d8df1751d8d",
"messageUuid": "c385bb6e-32f0-4952-a198-c5ed2a00161b",
"scheduled": false
},
]
}Body Parameters
| Key | Expected value | Description |
|---|---|---|
to | string | Destination mobile number |
body | string | Body content to send in message |
from.type | "custom"|"shared" | Type of sender ID being specified |
from.value | string | Sender ID |
callback | string | URL to send webhook/callback delivery receipts to |
channels | string[] | Priority ordered list of message channels to try sending via. Available channels |
id | string | UUID string identifier for the message |
send_at | string | ISO 8601 formatted timestamp, representing when to send this message. Expects a timestamp >5 minutes into the future. GMT timezone |
Specifying Defaults
Individual Messages in the messages.* array can have their parameters supplied by specifying them in the defaults parameter.
How request validation is performed with defaults
The content of each Message object in the messages array is merged over the top of any parameters provided in defaults. The messages array parameters will always take priority over defaults parameters.
Validation is then performed against the merged Messages.
In this example, I'm sending two messages with different destinations and body content, from the same sender ID. Rather than specifying the sender ID twice, I'm going to specify it once in the defaults:
POST
https://mplus.instagiv.com/message{
"defaults": {
"from": {
"type": "custom",
"value": "mplus-test"
}
},
"messages": [
{
"to": "441111111111",
"body": "This is the first test message!",
},
{
"to": "442222222222",
"body": "This is the second test message!",
},
{
"from": {
"type": "custom",
"value": "specific"
},
"to": "44333333333333",
"body": "This is the third test message!",
},
]
}response body
{
"messages": [
{
"to": "441111111111",
"body": "This is the first test message!",
"from": {
"type": "custom",
"value": "mplus-test"
},
"batchUuid": "8d5fea2b-f9cf-4daf-bd41-6b2126eb9619",
"messageUuid": "73eaee49-64df-4564-81ee-22752014eb78",
"scheduled": false
},
{
"to": "442222222222",
"body": "This is the second test message!",
"from": {
"type": "custom",
"value": "mplus-test"
},
"batchUuid": "115e7ab2-688a-47ac-a361-97b5721713e6",
"messageUuid": "6fe95d5f-9221-43ae-9a83-92c3d71014ca",
"scheduled": false
},
{
"to": "44333333333333",
"body": "This is the third test message!",
"from": {
"type": "custom",
"value": "specific"
},
"batchUuid": "96c364b3-7d5e-4f64-9586-a16b3affdedc",
"messageUuid": "8e5bc994-bf53-4aaf-82cf-cb29a29c2277",
"scheduled": false
},
]
}As shown here, the from parameter that I specified in defaults has now been put into the body of the messages
Specify Callback Endpoint
To receive Delivery receipts via Webhook requests, you can specify the endpoint on your system that you want them to be sent to.
POST
https://mplus.instagiv.com/message// Specify the callback endpoint in the message body
{
"messages": [
{
"from": {
"type": "custom",
"value": "mplus-test"
},
"to": "441111111111",
"body": "This is my test message!",
"callback": "https://my-website.com/delivery-receipt"
},
]
}// Specify different endpoints for different messages
{
"messages": [
{
"from": {
"type": "custom",
"value": "mplus-test"
},
"to": "441111111111",
"body": "This is my first test message!",
"callback": "https://my-website.com/dr?id=first_message"
},
{
"from": {
"type": "custom",
"value": "mplus-test"
},
"to": "442222222222",
"body": "This is my second test message!",
"callback": "https://my-website.com/dr?id=second_message"
},
]
}// Utilize defaults to set the same callback endpoint for
// all messages
{
"defualts": {
"from": {
"type": "custom",
"value": "specific"
},
"callback": "https://my-website.com/delivery-receipt"
},
"messages": [
{
"to": "441111111111",
"body": "This is my first test message!",
},
{
"to": "442222222222",
"body": "This is my second test message!",
},
{
"to": "443333333333",
"body": "This is my third test message!",
},
]
}Receiving delivery receipts: Delivery Receipt Webhooks
Specifying Channels
Specify which message channel you want to send via, and which ones you want to fall back through.
POST
https://mplus.instagiv.com/message{
"messages": [
{
"from": {
"type": "custom",
"value": "specific"
},
"to": "44333333333333",
"body": "This is the third test message!",
"channels": ["rcs"]
},
]
}Specifying Shared Sender IDs
To utilize a shared sender ID, you need to specify a shared from type.
POST
https://mplus.instagiv.com/message{
"messages": [
{
"from": {
"type": "shared"
},
"to": "44333333333333",
"body": "This is the third test message!",
"channels": ["rcs"]
},
]
}The rules for assigning a shared sender ID are as follows:
Step 1:
If a message has been previously sent under the following rules, send from the same shared sender ID:
- From the currently authenticated account
- Via a shared sender ID
- To the mobile number in the request
Then send from the same shared sender ID
Step 2:
Otherwise, randomly assign a new shared sender ID from the pool