# Send message

  • Send a message on Twilio SMS, Twilio WhatsApp or Gupshup WhatsApp channel.
  • You can also send one or more images or a file.
  • Optionally, you can also save recipient in a contact list.

# Method

POST

# Path

/message

# Body parameters

Name Value Data type Required?
provider twlo (for Twilio SMS),
twlowa (for Twilio WhatsApp),
gswa (for Gupshup WhatsApp)
String Yes
channel_key Channel key value from Profile & settings -> API String Yes
to Phone number starting with the country code with or without leading plus. e.g. +16175551212 or 16175551212 String Yes
name Recipient name String No
text Message text String No (when image_url, image_urls or file_url is present)
image_url Publicly accessible image URL String No (when text, image_urls or file_url is present)
image_urls Array of publicly accessible image URLs String No (when text, image_url or file_url is present)
file_url Publicly accessible file URL String No (when text, image_url or image_urls is present)
contact_saving Object with instruction to save phone number and name as a contact after sending the message. See below Object No

# contact_saving

This field is for passing instruction to save phone number and name as a contact. If the contact already exists, it will be updated. Extra custom fields can also be passed.

Name Value Data type Required?
save true - Save phone number, name and extra fields as a contact,
false - Skip saving as contact
Boolean No (defaults to false)
list_id 0 - to add to "All Contacts" or
List ID - to add to a contact list (List ID is the value shown in the header bar when a list is selected on the Contacts page)
Integer No (defaults to 0)
extra_fields Key value pair object with additional custom fields (e.g. { "email_address": "john@example.com", "id": 987123 }) Object No

# Response

# HTTP status codes

Code Description
200 Request was successful.
400 Validation error or request body was incorrectly formatted.
401 Authentication failed. Check apikey header.
404 Requested API endpoint not found.
429 The rate limit has been reached.
500-511 There was a problem processing the request on our server. Try again later.

# Response object

Name Value Description
status success or error -
errors Array of object { msg: [error detail] } Only present when status is error

# Code samples

# Sending only text content

curl --location --request POST 'https://api.sociocs.com/message' \
--header 'apikey: [your api key]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "provider": "[provider]",
    "channel_key": "[your channel key]",
    "to": "[phone number]",
    "name": "[recipient name]",
    "text": "[message]"
}'

# Sending text & image

curl --location --request POST 'https://api.sociocs.com/message' \
--header 'apikey: [your api key]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "provider": "[provider]",
    "channel_key": "[your channel key]",
    "to": "[phone number]",
    "name": "[recipient name]",
    "text": "[message]",
    "image_url": "[image url]"
}'

# Sending only images

curl --location --request POST 'https://api.sociocs.com/message' \
--header 'apikey: [your api key]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "provider": "[provider]",
    "channel_key": "[your channel key]",
    "to": "[phone number]",
    "name": "[recipient name]",
    "image_urls": [
        "[image url 1]",
        "[image url 2]",
        "[image url 3]"
    ]
}'