# iMessage-specific API You can use all TextLink tools, integrations and APIs for your [Blububl](https://blububl.com) 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](https://blububl.com/demo). 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](https://docs.textlinksms.com/api#sending-an-sms) and [receiving](https://docs.textlinksms.com/webhooks) 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](https://textlinksms.com/dashboard/api) | #### Request Body | Name | Type | Description | | ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | phone\_number\* | String | Phone number that you want to check. International format, with prefix, like **+11234567890** | | 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](https://textlinksms.com/dashboard/your-devices/overview), by clicking on the device having the SIM card you need | {% tabs %} {% tab title="200: OK iMessage number" %} ```javascript { ok: true, imessage: true } ``` {% endtab %} {% tab title="200: OK Number can't use iMessage" %} ```javascript { ok: true, imessage: false } ``` {% endtab %} {% tab title="200: NOT OK" %} ```javascript { ok: false, message: "Reason string" } ``` {% endtab %} {% endtabs %} ## 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](https://textlinksms.com/dashboard/api) | #### Request Body (As multipart form data) | Name | Type | Description | | ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | phone\_number\* | String | Phone number that you want to check. International format, with prefix, like **+11234567890** | | 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](https://textlinksms.com/dashboard/your-devices/overview), 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](https://docs.textlinksms.com/webhooks#failed-message) | {% tabs %} {% tab title="200: OK Message successfully sent" %} ```javascript { ok: true, price: 0, sim_card_id: 1088 } ``` {% endtab %} {% tab title="200: OK Message sending failed" %} ```javascript { ok: false, message: "Reason string" } ``` {% endtab %} {% endtabs %} ### Code snippets {% tabs %} {% tab title="Node.js" %} ```javascript // 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() ``` {% endtab %} {% tab title="Python" %} ```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() ``` {% endtab %} {% endtabs %} ## 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](https://textlinksms.com/dashboard/api) | #### Request Body (As multipart form data) | Name | Type | Description | | ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | phone\_number\* | String | Phone number that you want to check. International format, with prefix, like **+11234567890** | | 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](https://textlinksms.com/dashboard/your-devices/overview), 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](https://docs.textlinksms.com/webhooks#failed-message) | {% tabs %} {% tab title="200: OK Message successfully sent" %} ```javascript { ok: true, price: 0, sim_card_id: 1088 } ``` {% endtab %} {% tab title="200: OK Message sending failed" %} ```javascript { ok: false, message: "Reason string" } ``` {% endtab %} {% endtabs %} ### Code snippets {% tabs %} {% tab title="Node.js" %} ```javascript // 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() ``` {% endtab %} {% tab title="Python" %} ```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() ``` {% endtab %} {% endtabs %} ## 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](https://textlinksms.com/dashboard/api) | #### Request Body (As multipart form data) | Name | Type | Description | | ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | phone\_number\* | String | Phone number that you want to check. International format, with prefix, like **+11234567890** | | 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](https://textlinksms.com/dashboard/your-devices/overview), 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](https://docs.textlinksms.com/webhooks#failed-message) | {% tabs %} {% tab title="200: OK Message successfully sent" %} ```javascript { ok: true, price: 0, sim_card_id: 1088 } ``` {% endtab %} {% tab title="200: OK Message sending failed" %} ```javascript { ok: false, message: "Reason string" } ``` {% endtab %} {% endtabs %} ### Code snippets {% tabs %} {% tab title="Node.js" %} ```javascript // 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() ``` {% endtab %} {% tab title="Python" %} ```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() ``` {% endtab %} {% endtabs %} ## 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](https://textlinksms.com/dashboard/api) | #### Request Body (As multipart form data) | Name | Type | Description | | ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | phone\_number\* | String | Phone number that you want to check. International format, with prefix, like **+11234567890** | | 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](https://textlinksms.com/dashboard/your-devices/overview), 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](https://docs.textlinksms.com/webhooks#failed-message) | {% tabs %} {% tab title="200: OK Message successfully sent" %} ```javascript { ok: true, price: 0, sim_card_id: 1088 } ``` {% endtab %} {% tab title="200: OK Message sending failed" %} ```javascript { ok: false, message: "Reason string" } ``` {% endtab %} {% endtabs %} ### Code snippets {% tabs %} {% tab title="Node.js" %} ```javascript // 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() ``` {% endtab %} {% tab title="Python" %} ```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() ``` {% endtab %} {% endtabs %} ## Receiving media messages When you receive a media message, a [normal receive SMS webhook](https://docs.textlinksms.com/webhooks#received-message) is triggered, and the text of the message includes filename, and is formatted like this: 1. For voice messages: 2. For images: 3. For videos: 4. For files: