Messages
The messages endpoint can be used to send messages across all mediums supported by Message2Give. It can also be used to retrieve read receipts and message status. It is accessed via /messages.
POST Message
https://api.app.message2give.com/2019-01-23/messagesAuthentication Required: Yes
Description
Send a message to a contact using SMS, MMS, Voice, or Email.
Body Properties
| Property | Required | Type | Default | Description |
|---|---|---|---|---|
| to | Yes | String | The target recipient of the message. Must be a valid Message2Give contact. See the introduction page for more info about valid contacts. | |
| from | Yes | String | The sender of the message. Must be a valid Message2Give contact. | |
| type | Yes | String | Type of message being sent. Can only be "sms", "mms", "voice", or "email". | |
| content | No | String | The plaintext message being sent. For emails, you can use HTML instead. Either the content or template property is required in your request. (not for voice) | |
| template | No | String | ID of a Message2Give template. The template is used as the message content. This overrides the content property. Either the content or template property is required in your request. Learn more about templates on the Templates page of the API Docs. (not for voice) | |
| fields | No | Object | The JSON data to use for a message template. Some templates include placeholder values like {{name}}. This object defines those values. E.g {"name": "John"}. | |
| subject | No | String | The subject of the email (Email Only). | |
| cc | No | String | Comma-separated list of CC recipients (Email Only). E.g "abc@example.com,def@example.com". | |
| bcc | No | String | Comma-separated list of BCC recipients (Email Only). E.g "abc@example.com,def@example.com". | |
| offTheRecord | No | Boolean | false | Hashes the SMS message when it is stored as a transcript (SMS Only). Boolean. True activates the functionality. |
| simulated | No | Boolean | false | Does not actually send the message. Useful for testing. Boolean. True activates the functionality. |
| humanAudioFile | Voice calls need one of humanAudioFile or humanText | String | (Voice only) ID of the audio file to use for the call. | |
| humanText | Voice calls need one of humanAudioFile or humanText | String | (Voice only) The TTS message you want to be spoken for the call. | |
| survey | No | String | ID of the survey to attach at the end of the message. | |
| ttsGender | No | String | female | (Voice only) The gender of the text-to-speech voice in the call. |
| voicemailAudioFile | No | String | (Voice only) ID of the audio file to use for the voicemail. | |
| voicemailText | No | String | (Voice only) The TTS message you want to be spoken for the voicemail. |
The example below sends the message "How are you today?" from +61 400 000 001 to +61 400 000 000 via SMS.
Code Snippet
GET Messages
https://api.app.message2give.com/2019-01-23/messages?limit={limit}Authentication Required: Yes
Description
Retrieves the data from all messages sent via your workspace. This includes messages sent via API requests.
Query Parameters
- limit: the maximum number of messages to return. Will be automatically reduced if necessary. If not specified, a reasonable value will be selected by default.
Returned Data
nextPageUri and previousPageUri are additional endpoints you can request to. They are used to access the paginated results of the request beyond the "limit" cap. For example, requesting the nextPageUri will return the data from the next "page" of messages.
The uri endpoint of each message will return the individual message data for that message.
{
"messages": [
{
"created": "2024-08-08T11:34:29.000Z",
"id": "1234",
"from": "61400000001",
"receipts": {
"rejected": "2024-08-08T11:34:30.000Z"
},
"type": "sms",
"content": "How are you today?",
"to": "614000000000",
"uri": "/2019-01-23/messages/1234"
},
{
"created": "2024-08-05T11:08:31.000Z",
"id": "5678",
"from": "61400000001",
"receipts": {
"rejected": "2024-08-05T11:08:31.000Z"
},
"type": "sms",
"content": "How are you today?",
"to": "61400000000",
"uri": "/2019-01-23/messages/5678"
}
],
"uri": "/2019-01-23/messages",
"nextPageUri": "/2019-01-23/messages?offset=2&limit=2",
"previousPageUri": null,
"status": "OK"
}Code Snippet
GET Message
https://api.app.message2give.com/2019-01-23/messages/{message_id}Authentication Required: Yes
Description
Retrieve a singular message's details.
Path Parameters
| Property | Description |
|---|---|
| message_id | The ID of the message being retrieved. |
{
"messages": [
{
"created": "2023-09-22T00:08:52.000Z",
"id": "12345",
"from": "Message2Give",
"receipts": {
"delivered": "2023-09-22T00:08:53.000Z"
},
"type": "sms",
"content": "What is going on!?",
"to": "61400000000",
"uri": "/2019-01-23/messages/12345"
}
],
"uri": "/2019-01-23/messages/12345",
"status": "OK"
}Code Snippet
POST POSTback Inbound Message
POSTback Inbound MessageAuthentication Required: No
Description
You can setup a Virtual Number (VN) in your workspace to send and receive messages through. You can configure POSTback URLs for these VNs. When the VN receives a message, it will send a notification to the POSTback URL in real time.
You can configure these POSTback URLs at https://app.message2give.com/#/channels/virtual-numbers/list.
{
"messages" : [
{
"id" : "12345",
"content" : "Test",
"from" : "61400000000",
"type" : "sms",
"to" : "61400000001",
"created" : "2021-06-30T01:36:14.813Z",
// files array is included for any messages with the 'mms' type.
"files" : [
{
"id" : "56789",
"filename" : "Attch124.smil",
"url" : ""
},
]
}
]
}POST POSTback Delivery Receipt
POSTback Delivery ReceiptAuthentication Required: No
Description
You may nominate a POSTback URL for your API Key. When you send a message using the API key, it will send the message's delivery receipt to the POSTback URL.
You can configure this POSTback URL at https://app.message2give.com/#/channels/keys/list.
{
"uri" : "/2019-01-23/messages/1234",
"messages" : [
{
"uri" : "/2019-01-23/messages/1234",
"created" : "2019-01-23T10:14:12.000Z",
"receipts" : {
"simulated" : "2019-01-23T10:14:12.000Z",
"delivered" : "2019-01-23T10:14:12.000Z"
},
"to" : "61400000000",
"from" : "61400000001",
"id" : "1234",
"content" : "Hello, World!",
"type" : "sms"
}
]
}How is this guide?