# 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

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, video_url or file_url is present)
video_url	Publicly accessible video URL	String	No (when text, image_url or file_url is present)
file_url	Publicly accessible file URL	String	No (when text, image_url or video_url is present)
contact_saving	Object with instruction to save phone number and name as a contact after sending the message. See below	Object	No
schedule	ISO 8601 date & time (e.g., "2006-01-02T15:04:05-04:00")	String	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`.
data	Object `{ 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"
}'

curl --location "https://api.sociocs.com/message" --header "Content-Type: application/json" --header "apikey: your_api_key" --data "{ \"provider\": \"twlo\", \"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\": \"twlo\", \"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": "twlo",
  "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": "twlo",`+"
"+`
    "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\": \"twlo\",\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": "twlo",
  "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": "twlo",
  "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": "twlo",
  "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": "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"
}'

curl --location "https://api.sociocs.com/message" --header "Content-Type: application/json" --header "apikey: your_api_key" --data "{ \"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\"}"

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\": \"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\" }", 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": "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"
});

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": "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"`+"
"+`
}`)

  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\": \"twlo\",\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": "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"
});

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": "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"
}';
$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": "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"
})
headers = {
  'Content-Type': 'application/json',
  'apikey': 'your_api_key'
}

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

print(response.text)

# 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"
}'

curl --location "https://api.sociocs.com/message" --header "Content-Type: application/json" --header "apikey: your_api_key" --data "{ \"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\" }"

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\": \"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\" }", 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": "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",
});
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": "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",`+"
"+`
}`)

  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\": \"twlo\",\r\n    \"channel_key\": \"your_channel_key\",\r\n    \"to\": \"phone_number\",\r\n    \"name\": \"recipient_name\",\r\n    \"image_url\": \"https://fastly.picsum.photos/id/701/200/300.jpg?hmac=gVWdD9Rh_J0iGXpXOJAN7MZpGPrpeHX_M5JwGGvTSsI\",\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": "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",
});

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": "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"
}';
$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": "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"
})
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",
    "data": { "message_id": "Xyz12345" }
}

# When the API call was unsuccessful

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