# 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." }]
}