# 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

/messages

# 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 Remarks
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 Remarks
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]"
}'
curl --location "https://api.sociocs.com/message" --header "Content-Type: application/json" --header "apikey: [your api key]" --data "{ \"provider\": \"[provider]\", \"channel_key\": \"[your channel key]\", \"to\": \"[phone number]\", \"name\": \"[recipient name]\", \"text\": \"[message]\" }"
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sociocs.com/message");
request.Headers.Add("apikey", "[your api key]");
var content = new StringContent("{ \"provider\": \"[provider]\", \"channel_key\": \"[your channel key]\", \"to\": \"[phone number]\", \"name\": \"[recipient name]\", \"text\": \"[message]\" }", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
var headers = {
  'Content-Type': 'application/json',
  'apikey': '[your api key]'
};

var request = http.Request('POST', Uri.parse('https://api.sociocs.com/message'));

request.body = json.encode({
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "text": "[message]"
});

request.headers.addAll(headers);

http.StreamedResponse response = await request.send();

if (response.statusCode == 200) {
  print(await response.stream.bytesToString());
}
else {
  print(response.reasonPhrase);
}
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.sociocs.com/message"
  method := "POST"

  payload := strings.NewReader(`{`+"
"+`
    "provider": "[provider]",`+"
"+`
    "channel_key": "[your channel key]",`+"
"+`
    "to": "[phone number]",`+"
"+`
    "name": "[recipient name]",`+"
"+`
    "text": "[message]"`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("apikey", "[your api key]")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
// This sample uses OkHttp library
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"provider\": \"[provider]\",\r\n    \"channel_key\": \"[your channel key]\",\r\n    \"to\": \"[phone number]\",\r\n    \"name\": \"[recipient name]\",\r\n    \"text\": \"[message]\"\r\n}");
Request request = new Request.Builder()
  .url("https://api.sociocs.com/message")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("apikey", "[your api key]")
  .build();
Response response = client.newCall(request).execute();
// This sample uses Axios library
const axios = require('axios');
let data = JSON.stringify({
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "text": "[message]"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.sociocs.com/message',
  headers: { 
    'Content-Type': 'application/json', 
    'apikey': '[your api key]'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});
<?php
// This sample uses Guzzle library
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'apikey' => '[your api key]'
];
$body = '{
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "text": "[message]"
}';
$request = new Request('POST', 'https://api.sociocs.com/message', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
# This sample uses Requests library
import requests
import json

url = "https://api.sociocs.com/message"

payload = json.dumps({
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "text": "[message]"
})
headers = {
  'Content-Type': 'application/json',
  'apikey': '[your api key]'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

# 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]"
}'
curl --location "https://api.sociocs.com/message" --header "Content-Type: application/json" --header "apikey: [your api key]" --data "{ \"provider\": \"[provider]\", \"channel_key\": \"[your channel key]\", \"to\": \"[phone number]\", \"name\": \"[recipient name]\", \"text\": \"[message]\", \"image_url\": \"[image url]\"}"
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sociocs.com/message");
request.Headers.Add("apikey", "[your api key]");
var content = new StringContent("{ \"provider\": \"[provider]\", \"channel_key\": \"[your channel key]\", \"to\": \"[phone number]\", \"name\": \"[recipient name]\", \"text\": \"[message]\", \"image_url\": \"[image url]\" }", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
var headers = {
  'Content-Type': 'application/json',
  'apikey': '[your api key]'
};

var request = http.Request('POST', Uri.parse('https://api.sociocs.com/message'));

request.body = json.encode({
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "text": "[message]",
  "image_url": "[image url]"
});

request.headers.addAll(headers);

http.StreamedResponse response = await request.send();

if (response.statusCode == 200) {
  print(await response.stream.bytesToString());
}
else {
  print(response.reasonPhrase);
}
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.sociocs.com/message"
  method := "POST"

  payload := strings.NewReader(`{`+"
"+`
    "provider": "[provider]",`+"
"+`
    "channel_key": "[your channel key]",`+"
"+`
    "to": "[phone number]",`+"
"+`
    "name": "[recipient name]",`+"
"+`
    "text": "[message]"`+"
"+`
    "image_url": "[image url]"`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("apikey", "[your api key]")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
// This sample uses OkHttp library
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"provider\": \"[provider]\",\r\n    \"channel_key\": \"[your channel key]\",\r\n    \"to\": \"[phone number]\",\r\n    \"name\": \"[recipient name]\",\r\n    \"text\": \"[message]\"\r\n}");
Request request = new Request.Builder()
  .url("https://api.sociocs.com/message")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("apikey", "[your api key]")
  .build();
Response response = client.newCall(request).execute();
// This sample uses Axios library
const axios = require('axios');
let data = JSON.stringify({
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "text": "[message]",
  "image_url": "[image url]"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.sociocs.com/message',
  headers: { 
    'Content-Type': 'application/json', 
    'apikey': '[your api key]'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});
<?php
// This sample uses Guzzle library
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'apikey' => '[your api key]'
];
$body = '{
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "text": "[message]".
  "image_url": "[image url]"
}';
$request = new Request('POST', 'https://api.sociocs.com/message', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
# This sample uses Requests library
import requests
import json

url = "https://api.sociocs.com/message"

payload = json.dumps({
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "text": "[message]",
  "image_url": "[image url]"
})
headers = {
  'Content-Type': 'application/json',
  'apikey': '[your api key]'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

# 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]"
    ]
}'
curl --location "https://api.sociocs.com/message" --header "Content-Type: application/json" --header "apikey: [your api key]" --data "{ \"provider\": \"[provider]\", \"channel_key\": \"[your channel key]\", \"to\": \"[phone number]\", \"name\": \"[recipient name]\", \"image_urls\": [\"[image url 1]\", \"[image url 2]\", \"[image url 3]\"] }"
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sociocs.com/message");
request.Headers.Add("apikey", "[your api key]");
var content = new StringContent("{ \"provider\": \"[provider]\", \"channel_key\": \"[your channel key]\", \"to\": \"[phone number]\", \"name\": \"[recipient name]\", \"image_urls\": [\"[image url 1]\", \"[image url 2]\", \"[image url 3]\"] }", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
var headers = {
  'Content-Type': 'application/json',
  'apikey': '[your api key]'
};
var request = http.Request('POST', Uri.parse('https://api.sociocs.com/message'));
request.body = json.encode({
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "image_urls": [
    "[image url 1]",
    "[image url 2]",
    "[image url 3]"
  ]
});
request.headers.addAll(headers);

http.StreamedResponse response = await request.send();

if (response.statusCode == 200) {
  print(await response.stream.bytesToString());
}
else {
  print(response.reasonPhrase);
}
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.sociocs.com/message"
  method := "POST"

  payload := strings.NewReader(`{`+"
"+`
    "provider": "[provider]",`+"
"+`
    "channel_key": "[your channel key]",`+"
"+`
    "to": "[phone number]",`+"
"+`
    "name": "[recipient name]",`+"
"+`
    "image_urls": [`+"
"+`
        "[image url 1]",`+"
"+`
        "[image url 2]",`+"
"+`
        "[image url 3]"`+"
"+`
    ]`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("apikey", "[your api key]")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
// This sample uses OkHttp library
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"provider\": \"[provider]\",\r\n    \"channel_key\": \"[your channel key]\",\r\n    \"to\": \"[phone number]\",\r\n    \"name\": \"[recipient name]\",\r\n    \"image_urls\": [\r\n        \"[image url 1]\",\r\n        \"[image url 2]\",\r\n        \"[image url 3]\"\r\n    ]\r\n}");
Request request = new Request.Builder()
  .url("https://api.sociocs.com/message")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("apikey", "[your api key]")
  .build();
Response response = client.newCall(request).execute();
// This sample uses Axios library
const axios = require('axios');
let data = JSON.stringify({
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "image_urls": [
    "[image url 1]",
    "[image url 2]",
    "[image url 3]"
  ]
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.sociocs.com/message',
  headers: { 
    'Content-Type': 'application/json', 
    'apikey': '[your api key]'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});
<?php
// This sample uses Guzzle library
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'apikey' => '[your api key]'
];
$body = '{
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "image_urls": [
    "[image url 1]",
    "[image url 2]",
    "[image url 3]"
  ]
}';
$request = new Request('POST', 'https://api.sociocs.com/message', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
# This sample uses Requests library
import requests
import json

url = "https://api.sociocs.com/message"

payload = json.dumps({
  "provider": "[provider]",
  "channel_key": "[your channel key]",
  "to": "[phone number]",
  "name": "[recipient name]",
  "image_urls": [
    "[image url 1]",
    "[image url 2]",
    "[image url 3]"
  ]
})
headers = {
  'Content-Type': 'application/json',
  'apikey': '[your api key]'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

# Response object examples

# When the API call was successful

{
    "status": "success"
}

# When the API call was unsuccessful

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