Send MMS (Multimedia Message Service)

This API allows you to send Multimedia Message Service (MMS) messages using the Cellcast API. The API detects any invalid contact numbers and return which numbers are invalid or unsubscribed on the response body, ensuring that messages are sent only to valid and subscribed numbers.

Parameters for Send MMS API

Headers Parameters

Parameters	Description
Authorization	Please add provided Bearer token - linked to your Cellcast account. Check here

Request Body Parameters

Name	Example	Description
sender	Sender ID (Custom ID)	Sender ID (Custom ID): Valid characters: A-Z a-z 0-9, space, and Dash (-). A numeric sender ID can be a maximum length of 16 digits. An alpha-numeric Sender ID can be a maximum length of 11 characters. If 'from' is left blank, the system will default to 'Regular ID'. *Note: Price increases to 1.3 credits per SMS for Custom ID and dedicated numbers.
media	media.png | media.jpg	Media: A valid media file. Allowed extension: jpg, jpeg, png (Max. file size is 230 KB)
gif	url.gif	Input your gif url here. Allowed extension: gif.
message	MMS Text goes here	String - Required field. To add a new line to the message, use "\r\n" in the message string with only double quote
contacts	["+61400000000"]	JSON encoded Array - Required field. To send multiple SMS messages, provide the recipient numbers in a JSON-encoded array, such as ["+61400000000", "+61400000001"]. You can include up to 1,000 numbers in a single API call. Supported number formats include : "+61400000000", "61400000000", "0400000000", "400000000"
countryCode	61	Allowed values: 61

Code Samples

Post https://api.cellcast.com/api/v1/gatewaymms

cURL

curl --location 'https://api.cellcast.com/api/v1/gatewaymms' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{API_KEY}}' \
--form 'message="Test MMS from API"' \
--form 'contacts="["+61400000000", "+61400000001", "+61400000002"]"' \
--form 'media=@"<path_to_your_media_file>"' \
--form 'gif="https://media1.tenor.com/m/UTrLSr85tYEAAAAC/happy-cat-cat.gif"' \
--form 'sender="040000001"'

node.js

const axios = require("axios");
const FormData = require("form-data");
const fs = require("fs");

const sendMMS = async () => {
  try {
    const form = new FormData();
    form.append("message", "Test MMS from API");
    form.append("contacts", ["+61400000000", "+61400000001", "+61400000002]);
    form.append("media", fs.createReadStream("<path_to_your_media_file>"));
    form.append("gif", "https://media1.tenor.com/m/UTrLSr85tYEAAAAC/happy-cat-cat.gif");
    form.append("sender", "+6140000001");

    const response = await axios.post("https://api.cellcast.com/api/v1/gatewaymms", form, {
      headers: {
        ...form.getHeaders(),
        Authorization: "Bearer {{API_KEY}}",
      },
    });
    console.log(response.data);
  } catch (error) {
    console.error(error.response.data);
  }
};

Replace with the actual API key that you own.

This documentation provides details on how to send Multimedia Message Service (MMS) messages using the Cellcast API, including the required headers and request body parameters.

Responses

Response Body

Name	Example	Description
messageId	675161d8a000000000000000	A unique identifier for the message, automatically generated by the system.

200 Success

{
    "app_type": "web",
    "app_version": "1.0",
    "maintainence": 0,
    "new_version": 0,
    "force_update": 0,
    "invalid_token": 0,
    "refresh_token": "",
    "show_message": 0,
    "is_enc": false,
    "status": true,
    "message": "Request is being processed",
    "message_type": "toast",
    "data": {
        "queueResponse": [
            {
                "Contact": "400000002",
                "MessageId": "6752be535000000000000000",
                "Result": "Message added to queue."
            },
            {
                "Contact": "400000003",
                "MessageId": "6752be535000000000000000",
                "Result": "Message added to queue."
            },
            {
                "Contact": "400000004",
                "MessageId": "6752be535000000000000000",
                "Result": "Message added to queue."
            }
        ],
        "message": "success register all valid contacts to queue",
        "invalidContacts": [
            {
                "Contact": " \"1234567890\"",
                "Error": "Number is not valid",
                "ErrorType": "number_not_valid"
            },
            {
                "Contact": " \"62400000001']",
                "Error": "Number is not valid",
                "ErrorType": "number_not_valid"
            }
        ],
        "unsubscribeContacts": [
            "400000001"
        ],
        "totalValidContact": 3,
        "totalInvalidContact": 2,
        "totalUnsubscribeContact": 1
    },
    "error": {}
}

400 Invalid Sender Number

{
    "app_type": "web",
    "app_version": "1.0",
    "maintainence": 0,
    "new_version": 0,
    "force_update": 0,
    "invalid_token": 0,
    "refresh_token": "",
    "show_message": 0,
    "is_enc": false,
    "status": false,
    "message_type": "toast",
    "message": "Your sender id is not registered.",
    "data": {},
    "error": {
        "sender": "not_registered"
    }
}

400 Bad Request

{
  "code": 400,
  "message": "Contacts must either start with 61 or +61 and be exactly 11 digits long (e.g., 614xxxxxxxx or +614xxxxxxxx), or be 9 digits without the area code (e.g., 4xxxxxxxx)",
  "stack": "APIError: Contacts are required."
}

422 Unprocessable Entity (Credit is too Low)

{
    "app_type": "web",
    "app_version": "1.0",
    "maintainence": 0,
    "new_version": 0,
    "force_update": 0,
    "invalid_token": 0,
    "refresh_token": "",
    "show_message": 0,
    "is_enc": false,
    "status": false,
    "message_type": "toast",
    "message": "Your balance is too low for this request, please recharge.",
    "data": {},
    "error": {
        "errorMessage": "Your balance is too low for this request, please recharge."
    }
}

401 Unauthorized

{
  "code": 401,
  "message": "Token expired",
  "stack": "APIError: Token expired ...."
}