iMessage-specific API

You can use all TextLink tools, integrations and APIs for your Blububl devices. Blububl is an iMessage automation solution that allows you to utilize iMessage for personalized / automated communication with your leads. You can see how it works on this page.

Onboarding to BluBubl is custom for each customer, and you need to contact Blububl directly in order to use the service.

BluBubl is a cloud service, and you can't set it up yourself like you do with TextLink devices.

This section covers the specific APIs for iMessage, including the API for checking if number has IMessage, and the APIs for sending a media message.. You can also use the basic SMS functionalities like sending and receiving messages the same way as using normal TextLink.

Checking if phone number has iMessage

To check if phone number uses iMessage, you can send the following POST request with tool of your choice (like Postman), or use any of the programming languages that support REST API calls.

You can only do that if you have an iMessage device (that can only be set up by BluBubl team).

Using API

POST https://textlinksms.com/api/check-imessage

Headers

Name	Type	Description
Content-Type*		The value should be "application/json"
Authorization*		The value should be "Bearer API_KEY", where API_KEY is the API key that you can see in the API Console

Request Body

Name	Type	Description
phone_number*	String	Phone number that you want to check. International format, with prefix, like [phone]
sim_card_id	Number	(Optional) Id of the iMessage virtual SIM card that you want to use for the check. Can be found in the Devices Console, by clicking on the device having the SIM card you need

200: OK iMessage number

{
  ok: true,
  imessage: true
}

200: OK Number can't use iMessage

{
  ok: true,
  imessage: false
}

200: NOT OK

{
  ok: false,
  message: "Reason string"
}

Sending a voice note (using audio file)

Sending media messages, including voice notes, uses multipart form data for request body encoding, instead of JSON. It needs to be that way because it allows binary content, such as media, documents and other files.

Using API

POST https://textlinksms.com/media/send-voice

Headers

Name	Type	Description
Content-Type*		The value should be "multipart/form-data"
Authorization*		The value should be "Bearer API_KEY", where API_KEY is the API key that you can see in the API Console

Request Body (As multipart form data)

Name	Type	Description
phone_number*	String	Phone number that you want to check. International format, with prefix, like [phone]
voice*	File	Audio file (MP3, WAV, etc.) to send. The form‐field name must be voice.
sim_card_id	Number	(Optional) Id of the iMessage virtual SIM card that you want to use for the check. Can be found in the Devices Console, by clicking on the device having the SIM card you need
custom_id	String	(Optional) Custom id that you want us to send to you in our failed message webhook

200: OK Message successfully sent

{
    ok: true,
    price: 0,
    sim_card_id: 1088
}

200: OK Message sending failed

{
  ok: false,
  message: "Reason string"
}

Code snippets

Node.js

// Install dependencies first:
// npm install axios form-data

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

async function test() {
    const form = new FormData();
    form.append('phone_number', PHONE_NUMBER);
    form.append('voice', fs.createReadStream(path.resolve(FILE_PATH)));
    form.append('sim_card_id', SIM_CARD_ID);

    try {
        const response = await axios.post(
            'https://textlinksms.com/media/send-voice',
            form,
            {
                headers: {
                    'Authorization': 'Bearer ' + API_KEY,
                    ...form.getHeaders(),
                },
                maxBodyLength: Infinity,
            }
        );
        console.log('Response data:', response.data);
    } catch (err) {
        console.log(err);
    }
}

test()

Python

# Install dependencies first:
# pip install requests

import requests

def send_voice():
    url = "https://textlinksms.com/media/send-voice"
    headers = {
        "Authorization": f"Bearer {API_KEY}"
    }
    data = {
        "phone_number": PHONE_NUMBER,
        "sim_card_id": SIM_CARD_ID
    }
    with open(FILE_PATH, "rb") as voice_file:
        files = {
            "voice": voice_file
        }
        response = requests.post(url, headers=headers, data=data, files=files)
    
    try:
        response.raise_for_status()
        print("Response data:", response.json())
    except requests.HTTPError as e:
        # If the API returns a non-2xx status code, print the error response
        print(f"Error sending voice: {e}\n{response.text}")

if __name__ == "__main__":
    send_voice()

Sending a picture

Sending media messages, including images, uses multipart form data for request body encoding, instead of JSON. It needs to be that way because it allows binary content, such as media, documents and other files.

Using API

POST https://textlinksms.com/media/send-image

Headers

Name	Type	Description
Content-Type*		The value should be "multipart/form-data"
Authorization*		The value should be "Bearer API_KEY", where API_KEY is the API key that you can see in the API Console

Request Body (As multipart form data)

Name	Type	Description
phone_number*	String	Phone number that you want to check. International format, with prefix, like [phone]
image*	File	Image file (JPG, PNG, etc.) to send. The form‐field name must be image.
sim_card_id	Number	(Optional) Id of the iMessage virtual SIM card that you want to use for the check. Can be found in the Devices Console, by clicking on the device having the SIM card you need
custom_id	String	(Optional) Custom id that you want us to send to you in our failed message webhook

200: OK Message successfully sent

{
    ok: true,
    price: 0,
    sim_card_id: 1088
}

200: OK Message sending failed

{
  ok: false,
  message: "Reason string"
}

Code snippets

Node.js

// Install dependencies first:
// npm install axios form-data

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

async function test() {
    const form = new FormData();
    form.append('phone_number', PHONE_NUMBER);
    form.append('image', fs.createReadStream(path.resolve(FILE_PATH)));
    form.append('sim_card_id', SIM_CARD_ID);

    try {
        const response = await axios.post(
            'https://textlinksms.com/media/send-image',
            form,
            {
                headers: {
                    'Authorization': 'Bearer ' + API_KEY,
                    ...form.getHeaders(),
                },
                maxBodyLength: Infinity,
            }
        );
        console.log('Response data:', response.data);
    } catch (err) {
        console.log(err);
    }
}

test()

Python

# Install dependencies first:
# pip install requests

import requests

def send_image():
    url = "https://textlinksms.com/media/send-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}"
    }
    data = {
        "phone_number": PHONE_NUMBER,
        "sim_card_id": SIM_CARD_ID
    }
    with open(FILE_PATH, "rb") as image_file:
        files = {
            "image": image_file
        }
        response = requests.post(url, headers=headers, data=data, files=files)
    
    try:
        response.raise_for_status()
        print("Response data:", response.json())
    except requests.HTTPError as e:
        # If the API returns a non-2xx status code, print the error response
        print(f"Error sending image: {e}\n{response.text}")

if __name__ == "__main__":
    send_image()

Sending a video

Sending media messages, including videos, uses multipart form data for request body encoding, instead of JSON. It needs to be that way because it allows binary content, such as media, documents and other files.

Using API

POST https://textlinksms.com/media/send-video

Headers

Name	Type	Description
Content-Type*		The value should be "multipart/form-data"
Authorization*		The value should be "Bearer API_KEY", where API_KEY is the API key that you can see in the API Console

Request Body (As multipart form data)

Name	Type	Description
phone_number*	String	Phone number that you want to check. International format, with prefix, like [phone]
video*	File	Video file (MP4, MKV, etc.) to send. The form‐field name must be video.
sim_card_id	Number	(Optional) Id of the iMessage virtual SIM card that you want to use for the check. Can be found in the Devices Console, by clicking on the device having the SIM card you need
custom_id	String	(Optional) Custom id that you want us to send to you in our failed message webhook

200: OK Message successfully sent

{
    ok: true,
    price: 0,
    sim_card_id: 1088
}

200: OK Message sending failed

{
  ok: false,
  message: "Reason string"
}

Code snippets

Node.js

// Install dependencies first:
// npm install axios form-data

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

async function test() {
    const form = new FormData();
    form.append('phone_number', PHONE_NUMBER);
    form.append('video', fs.createReadStream(path.resolve(FILE_PATH)));
    form.append('sim_card_id', SIM_CARD_ID);

    try {
        const response = await axios.post(
            'https://textlinksms.com/media/send-video',
            form,
            {
                headers: {
                    'Authorization': 'Bearer ' + API_KEY,
                    ...form.getHeaders(),
                },
                maxBodyLength: Infinity,
            }
        );
        console.log('Response data:', response.data);
    } catch (err) {
        console.log(err);
    }
}

test()

Python

# Install dependencies first:
# pip install requests

import requests

def send_video():
    url = "https://textlinksms.com/media/send-video"
    headers = {
        "Authorization": f"Bearer {API_KEY}"
    }
    data = {
        "phone_number": PHONE_NUMBER,
        "sim_card_id": SIM_CARD_ID
    }
    with open(FILE_PATH, "rb") as video_file:
        files = {
            "video": video_file
        }
        response = requests.post(url, headers=headers, data=data, files=files)
    
    try:
        response.raise_for_status()
        print("Response data:", response.json())
    except requests.HTTPError as e:
        # If the API returns a non-2xx status code, print the error response
        print(f"Error sending video: {e}\n{response.text}")

if __name__ == "__main__":
    send_video()

Sending a file

Sending media and file messages uses multipart form data for request body encoding, instead of JSON. It needs to be that way because it allows binary content, such as media, documents and other files.

Using API

POST https://textlinksms.com/media/send-file

Headers

Name	Type	Description
Content-Type*		The value should be "multipart/form-data"
Authorization*		The value should be "Bearer API_KEY", where API_KEY is the API key that you can see in the API Console

Request Body (As multipart form data)

Name	Type	Description
phone_number*	String	Phone number that you want to check. International format, with prefix, like [phone]
file*	File	Any file (PDF, PPTX, etc.) to send. The form‐field name must be file.
sim_card_id	Number	(Optional) Id of the iMessage virtual SIM card that you want to use for the check. Can be found in the Devices Console, by clicking on the device having the SIM card you need
custom_id	String	(Optional) Custom id that you want us to send to you in our failed message webhook

200: OK Message successfully sent

{
    ok: true,
    price: 0,
    sim_card_id: 1088
}

200: OK Message sending failed

{
  ok: false,
  message: "Reason string"
}

Code snippets

Node.js

// Install dependencies first:
// npm install axios form-data

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

async function test() {
    const form = new FormData();
    form.append('phone_number', PHONE_NUMBER);
    form.append('file', fs.createReadStream(path.resolve(FILE_PATH)));
    form.append('sim_card_id', SIM_CARD_ID);

    try {
        const response = await axios.post(
            'https://textlinksms.com/media/send-file',
            form,
            {
                headers: {
                    'Authorization': 'Bearer ' + API_KEY,
                    ...form.getHeaders(),
                },
                maxBodyLength: Infinity,
            }
        );
        console.log('Response data:', response.data);
    } catch (err) {
        console.log(err);
    }
}

test()

Python

# Install dependencies first:
# pip install requests

import requests

def send_file():
    url = "https://textlinksms.com/media/send-file"
    headers = {
        "Authorization": f"Bearer {API_KEY}"
    }
    data = {
        "phone_number": PHONE_NUMBER,
        "sim_card_id": SIM_CARD_ID
    }
    with open(FILE_PATH, "rb") as my_file:
        files = {
            "file": my_file
        }
        response = requests.post(url, headers=headers, data=data, files=files)
    
    try:
        response.raise_for_status()
        print("Response data:", response.json())
    except requests.HTTPError as e:
        # If the API returns a non-2xx status code, print the error response
        print(f"Error sending file: {e}\n{response.text}")

if __name__ == "__main__":
    send_file()

Receiving media messages

When you receive a media message, a normal receive SMS webhook is triggered, and the text of the message includes filename, and is formatted like this:

1. For voice messages: https://textlinksms.com/uploads/voice/e022e743-8e0e-4ea1-8a29-d6404a85eaef.mp3
2. For images: https://textlinksms.com/uploads/images/5e2d687a-4640-424b-bd35-7e2e19a17a27.heic
3. For videos: https://textlinksms.com/uploads/videos/38471392-f2d8-4935-acf4-a0d7760d5079.mov
4. For files: https://textlinksms.com/uploads/files/b14d17cb-17ad-48e4-8495-2fa446151299-file_example_MP3_700KB.mp3