Campaigns
Send out a message automatically to hundreds of thousands of people all at once. Campaigns can be sent across SMS, Phone (Voice), Email, or MMS. A Validation Campaign is used to validate the status of a group of phone numbers.
A campaign is created, then started, then becomes active under certain conditions.
Learn more about campaigns at /guides/campaigns/general.
POST Campaign
https://api.app.message2give.com/2019-01-23/organisations/{workspace_id}/campaignsAuthentication Required: Yes
Description
Creates a campaign and sends it during a specified time period to a specified list of contacts. The campaign can be for SMS, Voice, Email, MMS, or Validation. The campaign message is sent to each contact individually, not all at once. The program will run through the list of contacts and finish when it reaches the end.
Path Parameters
| Property | Description |
|---|---|
| workspace_id | The ID of the workspace to create the campaign in. |
Body Properties
| Property | Required | Type | Default | Valid Campaign Type | Description |
|---|---|---|---|---|---|
| name | Yes | String | sms, mms, pstn, email, wash | The name of the campaign. | |
| type | Yes | String | sms, mms, pstn, email, wash | The type of campaign. Valid values: sms (SMS) pstn (Voice) email (Email) mms (MMS) wash (Validation). | |
| data | Yes | Array | sms, mms, pstn, email, wash | Information about your list of contacts. This is an array of Data Objects. Each object is for a different list of contacts. | |
| message | Yes | String | sms, mms, pstn, email | The message sent to your contact list. Will be played as a text-to-speech message when a voice call is picked up. Placeholders can be included by using {{Data Column Header}}. Contact records with a blank placeholder will be skipped. | |
| senderId | Yes | String | sms, mms, pstn, email, wash | A valid Sender ID, configured as a Virtual Number (SMS, MMS, Voice campaigns), Sender ID (SMS Campaigns) or Email Alias (Email campaigns) in the Message2Give Portal. | |
| times | Yes | Array | sms, mms, pstn, email, wash | Array of Times Objects that specify the campaigns active time periods. The campaign will only process messages while it is active. | |
| timezone | No | String | Etc/UTC | sms, mms, pstn, email, wash | Specifies the timezone the Message2Give Portal will display times in. Formatted as Country/City. |
| timeLimitHours | Yes | Number | sms, mms, pstn, email, wash | When set to 24, it will restrict the Message2Give Portal to only allow users to enter sending times restricted to the next 24 hours. | |
| rate | Yes | Number | sms, mms, pstn, email, wash | The number of messages that will be processed per hour. | |
| deduplicate | Yes | String | sms, mms, pstn, email, wash | Specifies the strategy used to deduplicate the contact file. Valid values: none - no deduplication destinations - only send messages to unique destinations messages - send only unique messages to a destination | |
| approved | Yes | Boolean | false | sms, mms, pstn, email, wash | When set to true, campaign issues will be automatically approved. When set to false, campaign issues will require a user login to the Message2Give Portal to manually approve the campaign before it can go live. |
| live | Yes | Boolean | false | sms, mms, pstn, email, wash | When set to true, the campaign will go live as soon as it is created. When set to false, the campaign will require a user login to the Message2Give Portal to manually set the campaign to go live. Note: Issues such as invalid numbers or missing placeholders will reset live to false unless the campaign is approved. |
| shortenUrls | Yes | String | Boolean | sms, mms, pstn, email, wash | Automatically shortens any URLs in the message. |
| exclusionList | No | Array | sms, mms, pstn, email, wash | Array of List IDs. Contacts in these List's will be excluded from the campaign. | |
| optOutList | No | String | sms, mms, pstn, email, wash | List ID. Contacts in this list will be excluded from the campaign. Opt-Outs from this campaign will automatically be added to this list. | |
| keywordReplies | No | Array | sms,mms,pstn | Array of [Keyword Replies Objects](#Keyword Replies) specifying how to automatically respond to incoming SMS replies based on keywords. Learn more about this at Keyword Replies. | |
| keywordRepliesTtl | No | Number | sms,mms,pstn | Duration in minutes after a message is sent before all configured keyword replies expire. | |
| optOutKeywords | No | Array | sms,mms | List of keywords to look for in reply SMS that will add the contact to the configured Opt-Out list. | |
| optOutMessage | No | String | sms,mms | An automated message sent to the contact after a successful opt-out. | |
| targetLanguageColumn | No | String | sms, mms | Column index in the contact file containing the language to deliver the message in. Contact a Message2Give Admin to enable on your workspace. | |
| subject | Yes | String | email | The subject of the message. | |
| attachments | mms: Yes email: No | Array | email, mms | Array of Attachments Objects to include in the message. MMS only support a single attachment, with a maximum size of 20MB for videos, 10MB for images, and 1.2MB for all other types. Email attachments must have a combined file size no greater than 20MB. | |
| audioFile | No | String | pstn | ID of the Audio File that will be played when a contact picks up a call. Overrides message. Uploading an aud file. | |
| voicemailMessage | No | String | pstn | Text-to-speech message that will be used when a call detects voicemail. | |
| voicemailAudioFile | No | String | pstn | ID of the Audio File that will be played when a call detects voicemail. Overrides voicemailMessage. Uploading an aud file. | |
| attempts | No | Number | 1 | pstn | Maximum number of calls to make to a number. Only calls that weren't picked up by a human will be reattempted. |
| attemptsRingTimeout | No | Number | 1 | pstn | Maximum number of call attempts that are allowed to ring out. |
| attemptsVoicemail | No | Number | 1 | pstn | Maximum number of call attempts that are allowed to go to voicemail. |
| attemptInterval | No | Number | 15 | pstn | Time between attempts in minutes. Cannot be less than 5. |
| ringTimeout | No | Number | 900 | pstn | Maximum number of seconds a call will ring for. |
| lastAttemptVoicemail | No | Boolean | false | pstn | When true, voicemail will only be left on the final call attempt. |
| witholdCallerId | No | Boolean | false | pstn | When true, the campaign's caller ID will be hidden from campaign recipients. |
| survey | No | String | pstn | ID of a Message2Give Survey that will run after the message has played. | |
| ttsGender | No | String | female | pstn | The gender of the text-to-speech voice. Can be either male or female. |
| inboundSurvey | No | String | pstn | ID of a Message2Give Survey that will run if the contact call's back. | |
| inboundTtl | No | Number | pstn | Duration in minutes after the outbound call is sent before the inbound survey expires. | |
| surveyMinCompletionsRequired | No | Number | pstn | When the connected surveys have reached this many completions, the campaing will automatically be paused. | |
| humanSms | No | String | pstn | SMS message that will be sent after the call is picked up. | |
| voicemailSms | No | String | pstn | SMS message that will be sent after a voicemail has been left. | |
| failSms | No | String | pstn | SMS message that will be sent after all call attempts have failed. |
Data
| Property | Required | Type | Default | Description |
|---|---|---|---|---|
| file | Yes | String | The ID for the file that containing your list of contacts. The file needs to be uploaded as a tgts type and must be a csv. This file will usually contain a column for contacts, and then adjacent columns for information about the contacts. You may also choose to add headers to the columns. Uploading a tgts file. | |
| fields | Yes | Array | Array containing all column headers. | |
| firstDataRow | Yes | Number | The index of the first row containing contact records. | |
| destinationIndex | Yes | Number | The column index containing the contact destination. | |
| fieldMap | No | Object | Object that specifies how to load contact data into Message2Give Chat Contact Attributes. Formatted as {"[columnIndex]": "Contact Attribute Name"} |
Times
Times must be formatted in the UTC timezone.
| Property | Required | Type | Default | Description |
|---|---|---|---|---|
| startTime | Yes | String | Starting time of the active period "HH:mm" | |
| endTime | Yes | String | Ending time of the active period "HH:mm" | |
| fromDate | No | String | Starting date of the active period | |
| toDate | No | String | Ending date of the active period | |
| weekdays | No | Array | Days of the week when the campaign is active. An array of numbers from 0-6, with 0 representing Sunday. |
Keyword Replies
| Property | Required | Type | Default | Description |
|---|---|---|---|---|
| keyword | Yes | Array | An array of strings to detect for in the reply. | |
| operator | Yes | String | Comparator used to evaluate keywords. Valid values: eq - reply is exactly equal to a keyword inc - reply contains a keyword sw - reply starts with a keyword ew - reply ends with a keyword ne - reply does not equal a keyword lt - reply is less than a keyword gt - reply is greater than a keyword. | |
| caseSensitive | No | Boolean | false | Case sensitivity of the keyword strings. |
| content | No | String | Automated SMS message sent after successfully matching a keyword. | |
| times | No | Array | Array of Times Objects that specify the time periods when the keyword is active. No specified times will enable the keyword reply at all times. | |
| enabled | No | Boolean | true | Enables keyword detection. |
| callMeDestination | No | String | A phone number that will be connected with the contact via a voice call when the keyword is triggered | |
| callMeAttempts | No | Number | 1 | Maximum number of calls to be made to the callMeDestination number. Failed calls will result in reattempts. |
| callMeWhisperText | No | String | A text-to-speech message played to the callMeDestination number to provide context about the call. | |
| callMeWhisperAudioFile | No | String | ID of the Audio File that will be played to the callMeDestination number to provide context about the call. Overrides callMeWhisperText. Uploading an aud file. | |
| callMeWhisperAttempts | No | Number | 1 | Number of times the whisper will be played to the callMeDestination number. |
| callMeFailSms | No | String | SMS message that will be sent if all call-me attempts have failed. |
Attachments
| Property | Required | Type | Default | Description |
|---|---|---|---|---|
| id | Yes | String | The ID of the file attachment. Uploading an oa file. | |
| filename | Yes | String | The name of the file. | |
| contentType | Yes | String | The files MIME type. | |
| size | Yes | Number | The size, in bytes, of the file (integer). | |
| contentDisposition | Yes | String | Only accepts "attachment". |
Code Snippet
GET Campaign
https://api.app.message2give.com/2019-01-23/organisations/{workspace_id}/campaigns/{campaign_id}Authentication Required: Yes
Description
Retrieves the details of a campaign from your workspace.
Path Parameters
| Property | Description |
|---|---|
| workspace_id | The workspace ID the campaign belongs to. |
| campaign_id | The ID of the campaign being retrieved. |
Code Snippet
POST Update Campaign
https://api.app.message2give.com/2019-01-23/organisations/{workspace_id}/campaigns/{campaign_id}Authentication Required: Yes
Description
Updates the details of a campaign in your workspace.
Path Parameters
| Property | Description |
|---|---|
| workspace_id | The ID of the workspace the campaign belongs to. |
| campaign_id | The ID of the campaign you are updating. |
Body Properties
To update any property of the campaign, include the property and its new value in the body of this request. To terminate the campaign, add a "terminate" property set to true. The campaign will not run again. To archive the campaign, add an "archive" property set to true. The campaign will be moved to an inactive archive, but you can unarchive these campaigns whenever desired.
Code Snippet
How is this guide?