This article walks step-by-step through sending an SMS message using the Volt GraphQL API.

We strongly suggest using a GraphQL client library in the language of your choice when interacting with the Volt GraphQL API. Using a GraphQL client library will make it easier to take advantage of static typing, API schema introspection, and other features that let you quickly and reliably build into the Volt GraphQL API. For more information, check out What is a GraphQL client and why would I use one?.

(blue star) Instructions

First, ensure that you have access to the data necessary for utilizing the Volt GraphQL API:

  1. Have your Volt GraphQL API access token readily available. If you are unsure of where to locate your API token, contact api@textvolt.com.

  2. To send an SMS message using the GraphQL API, you will need to specify the sending and receiving phone numbers, the message content, and a publicly accessible URL for media (if sending MMS).

A phone number can only be sent from if it belongs to your organization. If you are unsure of which phone numbers belong to your organization, log in to Volt or contact api@textvolt.com.

To ensure that phone numbers can be processed correctly by Volt, ensure that any phone numbers are formatted according to the E.164 standard. For example: (555) 555-0123 should be formatted as +15555550123.

Next, use the necessary data to send a message using the GraphQL API. For example, if you want to send an SMS message with the sending number +15555550123 and the receiving number +15555550145, construct a GraphQL API request:

  1. Set the Authorization header to the value Bearer <token>, replacing <token> with the API access token belonging to your organization.

  2. Construct a GraphQL query using the createMessage mutation:

    mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {
    createMessage (to: $to, from: $from, body: $body, media: $media) {
        id
        legacyId
        toNumber
        fromNumber
        status
        statusDescription
        media
        body
        sentAt
        confirmedAt
    }
}

  3. Construct a JSON object containing the GraphQL variables for the query created in the previous step:

    {
  "to": "+15555550145",
  "from": "+15555550123",
  "body": "Your One Time Code is 654312\n\nReply STOP to opt-out.",
  "media": []
}

    Note: to send an MMS message, set the media variable to a list of publicly-accessible media URLs corresponding to the media you wish to send. Supported file types are: JPEG, PNG, GIF, VCF (vCard).

  4. Send a POST request to https://api.respondflow.com/graphql with the GraphQL query and variables in the request body. We recommend using a GraphQL client library in the language of your choice to construct and send GraphQL API requests.

    For example, to send the above GraphQL request using curl:

    curl --location --request POST 'https://api.respondflow.com/graphql' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {\n    createMessage (to: $to, from: $from, body: $body, media: $media) {\n        id\n        legacyId\n        toNumber\n        fromNumber\n        status\n        statusDescription\n        media\n        body\n        sentAt\n        confirmedAt\n    }\n}","variables":{"to":"+15555550145","from":"+15555550123","body":"Your One Time Code is 654312\n\nReply STOP to opt-out.","media":[]}}'

(blue star) Related articles

(blue star) Examples by Language

These code snippets exhibit examples of sending SMS using the GraphQL API without using a GraphQL client library.

We strongly suggest using a GraphQL client library in the language of your choice when interacting with the Volt GraphQL API.

C#

var client = new RestClient("https://api.respondflow.com/graphql");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\"query\":\"mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {\\n    createMessage (to: $to, from: $from, body: $body, media: $media) {\\n        id\\n        legacyId\\n        toNumber\\n        fromNumber\\n        status\\n        statusDescription\\n        media\\n        body\\n        sentAt\\n        confirmedAt\\n    }\\n}\",\"variables\":{\"to\":\"+15555550145\",\"from\":\"+15555550123\",\"body\":\"Your One Time Code is 654312\\n\\nReply STOP to opt-out.\",\"media\":[]}}",
           ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Go

package main

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

func main() {

  url := "https://api.respondflow.com/graphql"
  method := "POST"

  payload := strings.NewReader("{\"query\":\"mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {\\n    createMessage (to: $to, from: $from, body: $body, media: $media) {\\n        id\\n        legacyId\\n        toNumber\\n        fromNumber\\n        status\\n        statusDescription\\n        media\\n        body\\n        sentAt\\n        confirmedAt\\n    }\\n}\",\"variables\":{\"to\":\"+15555550145\",\"from\":\"+15555550123\",\"body\":\"Your One Time Code is 654312\\n\\nReply STOP to opt-out.\",\"media\":[]}}")

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

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  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))
}

HTTP

POST /graphql HTTP/1.1
Host: api.respondflow.com
Authorization: Bearer <token>
Content-Type: application/json
Content-Length: 492

{"query":"mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {\n    createMessage (to: $to, from: $from, body: $body, media: $media) {\n        id\n        legacyId\n        toNumber\n        fromNumber\n        status\n        statusDescription\n        media\n        body\n        sentAt\n        confirmedAt\n    }\n}","variables":{"to":"+15555550145","from":"+15555550123","body":"Your One Time Code is 654312\n\nReply STOP to opt-out.","media":[]}}

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"query\":\"mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {\\n    createMessage (to: $to, from: $from, body: $body, media: $media) {\\n        id\\n        legacyId\\n        toNumber\\n        fromNumber\\n        status\\n        statusDescription\\n        media\\n        body\\n        sentAt\\n        confirmedAt\\n    }\\n}\",\"variables\":{\"to\":\"+15555550145\",\"from\":\"+15555550123\",\"body\":\"Your One Time Code is 654312\\n\\nReply STOP to opt-out.\",\"media\":[]}}");
Request request = new Request.Builder()
  .url("https://api.respondflow.com/graphql")
  .method("POST", body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

JavaScript (Node)

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.respondflow.com/graphql',
  'headers': {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: `mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {
    createMessage (to: $to, from: $from, body: $body, media: $media) {
        id
        legacyId
        toNumber
        fromNumber
        status
        statusDescription
        media
        body
        sentAt
        confirmedAt
    }
}`,
    variables: {"to":"+15555550145","from":"+15555550123","body":"Your One Time Code is 654312\n\nReply STOP to opt-out.","media":[]}
  })
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.respondflow.com/graphql',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{"query":"mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {\\n    createMessage (to: $to, from: $from, body: $body, media: $media) {\\n        id\\n        legacyId\\n        toNumber\\n        fromNumber\\n        status\\n        statusDescription\\n        media\\n        body\\n        sentAt\\n        confirmedAt\\n    }\\n}","variables":{"to":"+15555550145","from":"+15555550123","body":"Your One Time Code is 654312\\n\\nReply STOP to opt-out.","media":[]}}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer <token>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

import requests

url = "https://api.respondflow.com/graphql"

payload="{\"query\":\"mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {\\n    createMessage (to: $to, from: $from, body: $body, media: $media) {\\n        id\\n        legacyId\\n        toNumber\\n        fromNumber\\n        status\\n        statusDescription\\n        media\\n        body\\n        sentAt\\n        confirmedAt\\n    }\\n}\",\"variables\":{\"to\":\"+15555550145\",\"from\":\"+15555550123\",\"body\":\"Your One Time Code is 654312\\n\\nReply STOP to opt-out.\",\"media\":[]}}"
headers = {
  'Authorization': 'Bearer <token>',
  'Content-Type': 'application/json'
}

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

print(response.text)

Ruby

require "uri"
require "net/http"

url = URI("https://api.respondflow.com/graphql")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <token>"
request["Content-Type"] = "application/json"
request.body = "{\"query\":\"mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {\\n    createMessage (to: $to, from: $from, body: $body, media: $media) {\\n        id\\n        legacyId\\n        toNumber\\n        fromNumber\\n        status\\n        statusDescription\\n        media\\n        body\\n        sentAt\\n        confirmedAt\\n    }\\n}\",\"variables\":{\"to\":\"+15555550145\",\"from\":\"+15555550123\",\"body\":\"Your One Time Code is 654312\\n\\nReply STOP to opt-out.\",\"media\":[]}}"

response = https.request(request)
puts response.read_body

Unix shell (curl)

curl --location --request POST 'https://api.respondflow.com/graphql' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation createMessage ($to: String!, $from: String!, $body: String!, $media: [String!]) {\n    createMessage (to: $to, from: $from, body: $body, media: $media) {\n        id\n        legacyId\n        toNumber\n        fromNumber\n        status\n        statusDescription\n        media\n        body\n        sentAt\n        confirmedAt\n    }\n}","variables":{"to":"+15555550145","from":"+15555550123","body":"Your One Time Code is 654312\n\nReply STOP to opt-out.","media":[]}}'