Send MMS Programmatically

Preparation

In order to go through this how-to, you will need your CloudContactAI Client ID and API Key. Check the Getting Started Guide for the steps to obtain them.

Sending MMS Campaign

Sending a MMS requires three easy steps:

Request an upload URL for your file inside CloudContactAI storage.

To create your MMS you will need to upload your image/video to CloudContactAI storage. This requires calling an API endpoint that will give you a URL to PUT your file:

curl -X POST \
    -H "Authorization: Bearer <api_key>" \
	-H "Content-Type: application/json" \
	--data '{"fileName":"<timestamp>_sample_file_name.jpg","fileType":"<image_or_video_file_mime_type>","fileBasePath":"<your_client_id>/campaign","publicFile":true}' \
	"https://files.cloudcontactai.com/upload/url"

Remember to replace <api_key>, <timestamp>, <image_or_video_file_mime_type> and <your_client_id> with your own values. Once this request is executed, it will return a response like this:

{
  "signedS3Url":"https://cloudcontactai-prod-public.s3.amazonaws.com/<client_id>/campaign/<timestamp>_sample_file_name.jpg"
}

Upload your file to the given URL

Using the URL obtained on the previous step, proceed to upload a local image to CloudContactAI storage using a request like this:

curl -X PUT \
-H "Content-Type: <image_or_video_file_mime_type>" \
--upload-file "<your_local_file>.jpg" \
"<presigned_url_given_in_previous_step>"

Remember to replace <your_local_file> with the path of the file you want to upload and <presigned_url_given_in_previous_step> with the url you got as a response on the previous step.

Once done, this request will return an empty 200 response

Create your Campaign, including your uploaded image path

Finally, proceed to create a normal campaign, specifying all the basic data, including the key or path to the file you just uploaded, like this:

curl -X POST \
    -H "Authorization: Bearer <api_key>" \
	-H "Content-Type: application/json" \
	--data '{"pictureFileKey":"<client_id>/campaign/<timestamp>_sample_file_name","accounts":[{"firstName":"John","lastName":"Doe","phone":"+15555555555"},{"firstName":"Jane","lastName":"Doe","phone":"+12222222222"}],"message":"Hi ${firstName} ${lastName}, enjoy our little content!","title":"MMS Content Test"}' \
	"https://core.cloudcontactai.com/api/clients/<client_id>/campaigns/direct"

Remember to replace <api_key>, <client_id> and <timestamp> with your own values, having in mind that <timestamp> and <client_id> need to match the values used on step 1 to request your file upload URL.

Once this request returns, you will get a response like this

{
  "id": 12345,
  "message": "Hi ${firstName} ${lastName}, enjoy our little content!",
  "title": "MMS Content Test",
  "client": {
    "id": 6789,
    "name": "DEFAULT",
    "notifyIncomingSms": true,
    "incomingSmsCC": null,
    "incomingSmsMainEmail": true,
    "smsLimit": null,
    "deletedAt": null,
    "accountId": 101112,
    "apiKey": null,
    "errorRate": 0.0,
    "isTrusted": true
  },
  "senderPhone": null,
  "senderId": 12345,
  "createdDate": "2024-09-19T11:52:31.981314Z",
  "status": "PENDING",
  "fileKey": null,
  "startDate": null,
  "scheduledTimestamp": null,
  "scheduledTimezone": null,
  "endDate": null,
  "runAt": null,
  "useCopilot": false,
  "cron": null,
  "campaignType": "SMS",
  "scheduleMessage": null,
  "listId": 6789,
  "default": false,
  "totalError": null,
  "totalSent": null,
  "totalPending": null,
  "senderEmail": null,
  "editable": true,
  "positiveResponses": null,
  "negativeResponses": null,
  "campaignResources": null,
  "totalErrorRequeue": null,
  "listName": null,
  "syncList": false,
  "sentAt": null,
  "notes": null,
  "workflowId": null,
  "pendingApproval": null,
  "approvalMessage": null,
  "messageContainsUrl": false
}

This response confirms you campaign was created successfully, and will then be sent shortly.

Final Notes

Files have a maximum size of 1 mb to upload, any file bigger than 1 mb will fail to upload.
File uploads are not tied to specific campaigns, and thus, are reusable. That means you can upload your file once, and use the same file key on multiple campaigns without any drawback.