Powered by

#Send message

  • Send a message on Twilio SMS, Twilio WhatsApp or Gupshup WhatsApp channel.
  • You can also send an image, a video or a file.
  • You can schedule the message to be sent at a future date and time.
  • Optionally, you can also save the recipient in a contact list.
  • Calling this API with a future schedule date will create a scheduled message, which you can also see and update on app.sociocs.com -> Outbound -> Scheduled.

#Method

POST

#Path

/message

#Body parameters

NameValueData typeRequired?
providertwlo (for Twilio SMS),
twlowa (for Twilio WhatsApp),
gswa (for Gupshup WhatsApp)		StringYes
channel_keyChannel key value from Profile & settings -> APIStringYes
toPhone number starting with the country code with or without leading plus. e.g. +16175551212 or 16175551212StringYes
nameRecipient nameStringNo
textMessage textStringNo (when image_url, image_urls or file_url or template is present)
image_urlPublicly accessible image URL. Supported only when provider is twlo.StringNo (when text, video_url or file_url or template is present)
video_urlPublicly accessible video URL. Supported only when provider is twlo.StringNo (when text, image_url or file_url or template is present)
file_urlPublicly accessible file URL. Supported only when provider is twlo.StringNo (when text, image_url or video_url or template is present)
templateObject with template ID and variables. Used only when provider is either twlowa or gswa. See below for object format for each provider.ObjectNo (when text, image_url or video_url or file_url is present)
contact_savingObject with instruction to save phone number and name as a contact after sending the message. See belowObjectNo
scheduleISO 8601 date & time (e.g., "2006-01-02T15:04:05-04:00")StringNo
user_idSociocs user ID to show that user as sender of the message. When not provided, message is show as sent by Sociocs API. Use /team-members endpoint to find out User IDs.StringNo

#template

This field is used for passing template details when sending a WhatsApp template message. Applicable only when provider is either twlowa or gswa.

#template for provider twlowa

NameValueData typeRequired?
idTemplate SID from Twilio Content Template BuilderStringYes
variablesKey value pair object with all the variables in the template.

Example:
{ "1": "John", "2": "john@example.com", "3": "11-Jul-2024" }		ObjectYes (only when there are variables in the template)

#template for provider gswa

NameValueData typeRequired?
idTemplate ID for the template created in the Gupshup consoleStringYes
variablesObject with MEDIA_URL and/or key value pair object maps for each component (Header, Body, Buttons) with variables in the template.

Example:
{ "MEDIA_URL": "https://placehold.co/600x400", "Header": { "1": "John"}, "Body": { "1": "john@example.com", "2": "11-Jul-2024"}, "Buttons": {"1": "Quick Reply Text"} }		ObjectYes (only when there are variables in the template)

#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.

NameValueData typeRequired?
savetrue - Save phone number, name and extra fields as a contact,
false - Skip saving as contact		BooleanNo (defaults to false)
list_id0 - to add to "All Contacts" or
List ID - to add to a contact list (Use /lists endpoint to get all the contact lists)		IntegerNo (defaults to 0)
extra_fieldsKey value pair object with additional custom fields (e.g. { "email_address": "john@example.com", "id": 987123 })ObjectNo

#Response

#HTTP status codes

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

#Response object

NameValueRemarks
statussuccess or error-
errorsArray of object { msg: [error detail] }Only present when status is error.
dataObject { message_id: [new message id] }Only present when status is success.

#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": "twlo",
    "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": "twlo",
    "channel_key": "your_channel_key",
    "to": "phone_number",
    "name": "recipient_name",
    "text": "message",
    "image_url": "https://fastly.picsum.photos/id/1068/200/300.jpg?hmac=ICIwYXRGTpDxBPZAI7V8YxGtBBanV8Dfbe_DLNKtYcE"
}'

#Sending only an image

curl --location --request POST 'https://api.sociocs.com/message' \
--header 'apikey: your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "provider": "twlo",
    "channel_key": "your_channel_key",
    "to": "phone_number",
    "name": "recipient_name",
    "image_url": "https://fastly.picsum.photos/id/701/200/300.jpg?hmac=gVWdD9Rh_J0iGXpXOJAN7MZpGPrpeHX_M5JwGGvTSsI"
}'

#Response object examples

#When the API call was successful

{
    "status": "success",
    "data": { "message_id": "Xyz12345" }
}

#When the API call was unsuccessful

{
    "status": "error",
    "errors": [{ "msg": "Invalid channel_key." }]
}

    © 2025. All rights reserved.