Volt GraphQL API

The Volt GraphQL API is the primary way for apps to interact with the Volt platform.

Contact

API Endpoints

Production Server:
https://api.respondflow.com/v1.0/graphql

Version: 1

Respond Flow

Prior to 2022, Volt was known as Respond Flow. As we're making the transition to our new name, you may see technical details and domains that refer to Respond Flow throughout the documentation. Note that this is not a mistake, and no support for existing endpoints will be dropped for customers once the transition is complete.

Retrieving an Access Token

To generate an access token, log in to your Volt account, navigate to Settings and click the Developers tab. If the tab is not available, be sure your user has proper permissions to manage users in Volt.

Validating Webhooks

Each Volt webhook event that we send you will include a cryptographic signature in the X-Respond-Flow-Signature header. The signature allows you to validate that webhooks were not sent by a third-party. Our RSA public key is available at https://callbacks.respondflow.com/id_rsa.pub, which can be used to validate the signature sent with each request using a standard cryptographic library in your language of choice.

GraphQL Quick Intro

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

Below is an example using python

Endpoint

You will use the API endpoint documented at the top of this page

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

Headers

Your authorization will be your Bearer token

headers = {
    "Content-Type": 'application/json',
    "Authorization": "Bearer GENERATED_TOKEN"}

Variables

Where you see $variable: Type! in the examples, these should be passed beside the query

variables = {'primaryPhone':"+10003334444", 'phoneNumber': "+10000000464"}

Query Building

One of the benefits of GraphQL is that it will only return you the data you request, but this means that you must specify all the fields you need from the data. Where an example query may have many fields available

query contact(
     \$primaryPhone: String!,
     \$phoneNumber: String!
  ) {
    contact(
      primaryPhone: \$primaryPhone,
      phoneNumber: \$phoneNumber
    ) {
      id
      account {
        ...AccountFragment
      }
      organization {
        ...OrganizationFragment
      }
      phoneNumber
      name
      mappedNumber
      customFields {
        ...ContactCustomFieldFragment
      }
      createdAt
      lastUpdatedAt
      lists {
        ...ListFragment
      }
      blocked
    }
  }

You could reduce them to only the fields you want in the query

query contact(
  \$primaryPhone: String!,
  \$phoneNumber: String!
) {
  contact(
    primaryPhone: \$primaryPhone,
    phoneNumber: \$phoneNumber
  ) {
    name
    mappedNumber
    lastUpdatedAt
    blocked
  }
}

Similarly, the Contact object example has connected sub-objects (such as an Account attached to a Contact) and does not show all the fields of those sub-objects.

account {
        ...AccountFragment
      }

To get these sub-objects, you will need to expand their fields from linked types:

AccountFragment-> Account
OrganizationFragment-> Organization,
ListFragment-> List

query contact(\$primaryPhone: String!, \$phoneNumber: String!) {
contact(primaryPhone: \$primaryPhone, phoneNumber: \$phoneNumber) {
  id
  account {
    id,
    createdBy,
    organization {
      id,
      companyName,
      domain,
      size,
      industry,
      createdAt,
      lastUpdatedAt,
      isOnFreeTrial,
      isActive},
    name,
    primaryPhone,
    createdAt,
    lastUpdatedAt,
    callForwardingNumber,
    location
  }
  organization {
          id,
          companyName,
          domain,
          size,
          industry,
          createdAt,
          lastUpdatedAt,
          isOnFreeTrial,
          isActive
  }
  phoneNumber
  name
  mappedNumber
  customFields {
    key
    type
    value
  }
  createdAt
  lastUpdatedAt
  lists {    
    id
    createdBy
    name
    createdAt
    lastUpdatedAt
    size
    querySourceListName
    queryNameSearchTerm
  }
  blocked
}
}

Expanding all the sub-objects can make it repetitive. You also may not care about every field for these sub-objects. You can reduce them just as you can the main fields in the query.

query_text = """
  query contact(\$primaryPhone: String!, \$phoneNumber: String!) {
    contact(primaryPhone: \$primaryPhone, phoneNumber: \$phoneNumber) {
      id
      account {
        name,
        primaryPhone
      }
      organization {
        id,
        companyName
      }
      phoneNumber
      name
      mappedNumber
      createdAt
      lastUpdatedAt
      lists {    
        id
        Name
      }
      blocked
    }
  }
"""

Sending the Request

With all the above, we can now use a graphql library with an http transport to send this along

from gql import Client, gql
from gql.transport.aiohttp import AIOHTTPTransport
# Create a transport with the endpoint and headers
transport = AIOHTTPTransport(url=url, headers=headers)
# Create a GraphQL client using the AIOHTTPTransport transport
client = Client(transport=transport, fetch_schema_from_transport=True)
# Give gql the query
query = gql(query_text)
# Execute the query with variables
result = client.execute(query, variable_values=variables)
print(result)

The same can be achieved with the requests library, but note that querying requires a POST request

import requests
import json
response = requests.post(url=url, json={"query": query_text, "variables": variables}, headers=headers)
print("response status code: ", response.status_code)
if response.status_code == 200:
    content = json.loads(response.content)
    print(content['data'])
else:
    print(response.content)

Queries

`contact`

Get a contact by phone number

Returns a Contact

Name	Description
`primaryPhone` - `String!`	Primary number on the Volt account (as shown in the interface)
`phoneNumber` - `String!`	Phone number of the desired contact

Example

Query

query contact($primaryPhone: String!, $phoneNumber: String!) {
  contact(primaryPhone: $primaryPhone, phoneNumber: $phoneNumber) {
    id
    account {
      ...AccountFragment
    }
    organization {
      ...OrganizationFragment
    }
    phoneNumber
    name
    mappedNumber
    customFields {
      ...ContactCustomFieldFragment
    }
    createdAt
    lastUpdatedAt
    lists {
      ...ListFragment
    }
    blocked
  }
}

Variables

{"primaryPhone": "xyz789", "phoneNumber": "abc123"}

Response

{
  "data": {
    "contact": {
      "id": 1234,
      "account": Account,
      "organization": Organization,
      "phoneNumber": "+15555556893",
      "name": "Wile E. Coyote",
      "mappedNumber": "+15555551234",
      "customFields": [ContactCustomField],
      "createdAt": "2021-03-29T20:00:35.344134Z",
      "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
      "lists": [List],
      "blocked": true
    }
  }
}

Queries

`conversation`

Get a conversation between two entities

Returns a Conversation!

Name	Description
`to` - `String!`	Outgoing number
`from` - `String!`	Your Volt number (as shown in UI)
`before` - `String`	Base 64 encoded cursor

Example

Query

query conversation($to: String!, $from: String!, $before: String) {
  conversation(to: $to, from: $from, before: $before) {
    messages {
      ...MessageFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}

Variables

{
  "to": "+15555551234",
  "from": "+15555554321",
  "before": "<cursor>"
}

Response

{
  "data": {
    "conversation": {
      "messages": [Message],
      "pageInfo": PageInfo
    }
  }
}

Queries

`inbox`

Get inbox for account

Returns an Inbox

Name	Description
`from` - `String!`	Primary number on the Volt account (as shown in the interface)
`before` - `String`	Base 64 encoded cursor

Example

Query

query inbox($from: String!, $before: String) {
  inbox(from: $from, before: $before) {
    account {
      ...AccountFragment
    }
    items {
      ...InboxMessageFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}

Variables

{
  "from": "+15555554321",
  "before": "<cursor>"
}

Response

{
  "data": {
    "inbox": {
      "account": Account,
      "items": [InboxMessage],
      "pageInfo": PageInfo
    }
  }
}

Queries

`legacyMessage`

Get a message by provider ID

Returns a Message

Name	Description
`id` - `ID!`	Message ID assigned by telecom provider (uuid)

Example

Query

query legacyMessage($id: ID!) {
  legacyMessage(id: $id) {
    id
    legacyId
    account {
      ...AccountFragment
    }
    organization {
      ...OrganizationFragment
    }
    toNumber
    fromNumber
    status
    statusDescription
    media
    body
    sentAt
    confirmedAt
    wave {
      ...WaveFragment
    }
    contact {
      ...ContactFragment
    }
    errorCode
  }
}

Variables

{"id": ID}

Response

{
  "data": {
    "legacyMessage": {
      "id": rf_1234abcd,
      "legacyId": "40317653-15ed-444e-b232-98933f63adf8",
      "account": Account,
      "organization": Organization,
      "toNumber": "+15555556893",
      "fromNumber": "+15555556894",
      "status": "received",
      "statusDescription": "Incoming message received",
      "media": [
        [
          "https://example.com/image.png"
        ]
      ],
      "body": "Well, back to the old drawing board.",
      "sentAt": "2021-03-29T20:00:35.344134Z",
      "confirmedAt": "2021-03-29T20:00:35.344134Z",
      "wave": Wave,
      "contact": Contact,
      "errorCode": "xyz789"
    }
  }
}

Queries

`list`

Get a list

Returns a List!

Name	Description
`primaryPhone` - `String!`	Primary number on the Volt account (as shown in the interface)
`listName` - `String!`	Name of the desired list to fetch

Example

Query

query list($primaryPhone: String!, $listName: String!) {
  list(primaryPhone: $primaryPhone, listName: $listName) {
    id
    createdBy
    name
    createdAt
    lastUpdatedAt
    account {
      ...AccountFragment
    }
    size
    querySourceListName
    queryNameSearchTerm
    queryCustomFields {
      ...ListQueryRuleFragment
    }
  }
}

Variables

{
  "primaryPhone": "+15555554321",
  "listName": "Loyal Customers"
}

Response

{
  "data": {
    "list": {
      "id": 12345,
      "createdBy": "your.user@example.com",
      "name": "Loyal Customers",
      "createdAt": "2021-03-29T20:00:35.344134Z",
      "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
      "account": Account,
      "size": 542,
      "querySourceListName": "All",
      "queryNameSearchTerm": ,
      "queryCustomFields": [ListQueryRule]
    }
  }
}

Queries

`message`

Get a message by Volt ID

Returns a Message

Name	Description
`id` - `ID!`	Volt ID of a message (rf_*)

Example

Query

query message($id: ID!) {
  message(id: $id) {
    id
    legacyId
    account {
      ...AccountFragment
    }
    organization {
      ...OrganizationFragment
    }
    toNumber
    fromNumber
    status
    statusDescription
    media
    body
    sentAt
    confirmedAt
    wave {
      ...WaveFragment
    }
    contact {
      ...ContactFragment
    }
    errorCode
  }
}

Variables

{"id": ID}

Response

{
  "data": {
    "message": {
      "id": rf_1234abcd,
      "legacyId": "40317653-15ed-444e-b232-98933f63adf8",
      "account": Account,
      "organization": Organization,
      "toNumber": "+15555556893",
      "fromNumber": "+15555556894",
      "status": "received",
      "statusDescription": "Incoming message received",
      "media": [
        [
          "https://example.com/image.png"
        ]
      ],
      "body": "Well, back to the old drawing board.",
      "sentAt": "2021-03-29T20:00:35.344134Z",
      "confirmedAt": "2021-03-29T20:00:35.344134Z",
      "wave": Wave,
      "contact": Contact,
      "errorCode": "xyz789"
    }
  }
}

Queries

`wave`

Get a wave by ID

Returns a Wave

Name	Description
`id` - `ID!`	Numeric id assigned to a Wave given in the id attribute

Example

Query

query wave($id: ID!) {
  wave(id: $id) {
    id
    scheduledTime
    name
    account {
      ...AccountFragment
    }
    organization {
      ...OrganizationFragment
    }
    body
    media
    sentBy
    lists {
      ...ListFragment
    }
    totalMessages
    totalMessagesDelivered
    totalMessagesFailed
    type
  }
}

Variables

{"id": ID}

Response

{
  "data": {
    "wave": {
      "id": 12345,
      "scheduledTime": "xyz789",
      "name": "Memorial Day Brick Sale",
      "account": Account,
      "organization": Organization,
      "body": "Hi {contact.first_name}, we're having a great sale on bricks this weekend.",
      "media": [
        [
          "https://example.com/image.png"
        ]
      ],
      "sentBy": "your.user@example.com",
      "lists": [List],
      "totalMessages": 100,
      "totalMessagesDelivered": 98,
      "totalMessagesFailed": 2,
      "type": "account"
    }
  }
}

Queries

`webhooks`

Get all webhooks

Returns [Webhook]!

Example

Query

query webhooks {
  webhooks {
    id
    organization {
      ...OrganizationFragment
    }
    url
    createdAt
    lastUpdatedAt
    primaryPhone
    eventTypes
  }
}

Response

{
  "data": {
    "webhooks": [
      {
        "id": 1234,
        "organization": Organization,
        "url": "https://example.com/webhook",
        "createdAt": "2021-03-29T20:00:35.344134Z",
        "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
        "primaryPhone": "+15555556893",
        "eventTypes": [WebhookEventType]
      }
    ]
  }
}

Mutations

`addContactsToList`

Add one or many contacts to an existing list

Returns a List!

Name	Description
`primaryPhone` - `String!`	Primary number on the Volt account (as shown in the interface)
`listName` - `String!`	The name of the list; must be unique per account
`phoneNumbers` - `[String!]!`	The phone numbers of contacts to add to the list

Example

Query

mutation addContactsToList($primaryPhone: String!, $listName: String!, $phoneNumbers: [String!]!) {
  addContactsToList(primaryPhone: $primaryPhone, listName: $listName, phoneNumbers: $phoneNumbers) {
    id
    createdBy
    name
    createdAt
    lastUpdatedAt
    account {
      ...AccountFragment
    }
    size
    querySourceListName
    queryNameSearchTerm
    queryCustomFields {
      ...ListQueryRuleFragment
    }
  }
}

Variables

{
  "primaryPhone": "+15555556893",
  "listName": "Loyal Customers",
  "phoneNumbers": [
    [+15555551277, (555) KL5-1234]
  ]
}

Response

{
  "data": {
    "addContactsToList": {
      "id": 12345,
      "createdBy": "your.user@example.com",
      "name": "Loyal Customers",
      "createdAt": "2021-03-29T20:00:35.344134Z",
      "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
      "account": Account,
      "size": 542,
      "querySourceListName": "All",
      "queryNameSearchTerm": ,
      "queryCustomFields": [ListQueryRule]
    }
  }
}

Mutations

`createMessage`

Send a message

Returns a Message!

Name	Description
`to` - `String!`	Number to which to send the message
`from` - `String!`	Primary number on the Volt account (as shown in the interface, the message will be mapped appropriately)
`body` - `String!`	Text body of the message
`media` - `[String!]`	Media (URLs) to attach to the image

Example

Query

mutation createMessage($to: String!, $from: String!, $body: String!, $media: [String!]) {
  createMessage(to: $to, from: $from, body: $body, media: $media) {
    id
    legacyId
    account {
      ...AccountFragment
    }
    organization {
      ...OrganizationFragment
    }
    toNumber
    fromNumber
    status
    statusDescription
    media
    body
    sentAt
    confirmedAt
    wave {
      ...WaveFragment
    }
    contact {
      ...ContactFragment
    }
    errorCode
  }
}

Variables

{
  "to": "+15555556893",
  "from": "+15555556894",
  "body": "Thanks for coming in!",
  "media": [
    "https://example.com/thanks.png"
  ]
}

Response

{
  "data": {
    "createMessage": {
      "id": rf_1234abcd,
      "legacyId": "40317653-15ed-444e-b232-98933f63adf8",
      "account": Account,
      "organization": Organization,
      "toNumber": "+15555556893",
      "fromNumber": "+15555556894",
      "status": "received",
      "statusDescription": "Incoming message received",
      "media": [
        [
          "https://example.com/image.png"
        ]
      ],
      "body": "Well, back to the old drawing board.",
      "sentAt": "2021-03-29T20:00:35.344134Z",
      "confirmedAt": "2021-03-29T20:00:35.344134Z",
      "wave": Wave,
      "contact": Contact,
      "errorCode": "xyz789"
    }
  }
}

Mutations

`createOrUpdateContact`

Create or update a contact

Returns a Contact!

Name	Description
`name` - `String!`	Display name of the contact
`phoneNumber` - `String!`	Contact's phone number
`accountPhone` - `String!`	Primary number on the Volt account (as shown in the interface)
`customFields` - `[ContactCustomFieldInput]!`	Key-value pairs containing other identifying information on the contact
`blocked` - `Boolean!`	If the contact should be marked as blocked, and receivals not processed

Example

Query

mutation createOrUpdateContact($name: String!, $phoneNumber: String!, $accountPhone: String!, $customFields: [ContactCustomFieldInput]!, $blocked: Boolean!) {
  createOrUpdateContact(name: $name, phoneNumber: $phoneNumber, accountPhone: $accountPhone, customFields: $customFields, blocked: $blocked) {
    id
    account {
      ...AccountFragment
    }
    organization {
      ...OrganizationFragment
    }
    phoneNumber
    name
    mappedNumber
    customFields {
      ...ContactCustomFieldFragment
    }
    createdAt
    lastUpdatedAt
    lists {
      ...ListFragment
    }
    blocked
  }
}

Variables

{
  "name": "Wile E. Coyote",
  "phoneNumber": "+15555554321",
  "accountPhone": "+15555551234",
  "customFields": [ContactCustomFieldInput],
  "blocked": false
}

Response

{
  "data": {
    "createOrUpdateContact": {
      "id": 1234,
      "account": Account,
      "organization": Organization,
      "phoneNumber": "+15555556893",
      "name": "Wile E. Coyote",
      "mappedNumber": "+15555551234",
      "customFields": [ContactCustomField],
      "createdAt": "2021-03-29T20:00:35.344134Z",
      "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
      "lists": [List],
      "blocked": true
    }
  }
}

Mutations

`createOrUpdateList`

Create a or update a list

Returns a List!

Name	Description
`primaryPhone` - `String!`	Primary number on the Volt account (as shown in the interface)
`listQuery` - `ListQuery!`	List building information

Example

Query

mutation createOrUpdateList($primaryPhone: String!, $listQuery: ListQuery!) {
  createOrUpdateList(primaryPhone: $primaryPhone, listQuery: $listQuery) {
    id
    createdBy
    name
    createdAt
    lastUpdatedAt
    account {
      ...AccountFragment
    }
    size
    querySourceListName
    queryNameSearchTerm
    queryCustomFields {
      ...ListQueryRuleFragment
    }
  }
}

Variables

{
  "primaryPhone": "+15555556893",
  "listQuery": ListQuery
}

Response

{
  "data": {
    "createOrUpdateList": {
      "id": 12345,
      "createdBy": "your.user@example.com",
      "name": "Loyal Customers",
      "createdAt": "2021-03-29T20:00:35.344134Z",
      "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
      "account": Account,
      "size": 542,
      "querySourceListName": "All",
      "queryNameSearchTerm": ,
      "queryCustomFields": [ListQueryRule]
    }
  }
}

Mutations

`deleteWebhook`

Delete a webhook by id

Returns a Webhook

Name	Description
`id` - `ID!`	Numeric id assigned to a Webhook given in the id attribute

Example

Query

mutation deleteWebhook($id: ID!) {
  deleteWebhook(id: $id) {
    id
    organization {
      ...OrganizationFragment
    }
    url
    createdAt
    lastUpdatedAt
    primaryPhone
    eventTypes
  }
}

Variables

{"id": ID}

Response

{
  "data": {
    "deleteWebhook": {
      "id": 1234,
      "organization": Organization,
      "url": "https://example.com/webhook",
      "createdAt": "2021-03-29T20:00:35.344134Z",
      "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
      "primaryPhone": "+15555556893",
      "eventTypes": [WebhookEventType]
    }
  }
}

Mutations

`registerWebhook`

Create a webhook destination

Returns a Webhook

Name	Description
`url` - `String!`	URL of the POST request Volt will make with a message status update
`primaryPhone` - `String`	Root phone number of a specific account with which webhook is registered; defaults to all if not specified
`eventTypes` - `[WebhookEventType]`	A list of events that will trigger a webhook; requires `primaryPhone` to be specified; defaults to all

Example

Query

mutation registerWebhook($url: String!, $primaryPhone: String, $eventTypes: [WebhookEventType]) {
  registerWebhook(url: $url, primaryPhone: $primaryPhone, eventTypes: $eventTypes) {
    id
    organization {
      ...OrganizationFragment
    }
    url
    createdAt
    lastUpdatedAt
    primaryPhone
    eventTypes
  }
}

Variables

{
  "url": "https://example.com/webhook",
  "primaryPhone": "+15555556893",
  "eventTypes": [WebhookEventType]
}

Response

{
  "data": {
    "registerWebhook": {
      "id": 1234,
      "organization": Organization,
      "url": "https://example.com/webhook",
      "createdAt": "2021-03-29T20:00:35.344134Z",
      "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
      "primaryPhone": "+15555556893",
      "eventTypes": [WebhookEventType]
    }
  }
}

Mutations

`scheduleMessage`

Schedule a singular message

Returns a Wave

Name	Description
`primaryPhone` - `String!`	Primary number on the Volt account (as shown in the interface)
`message` - `MessageSchedulingJob!`	Other messaging information

Example

Query

mutation scheduleMessage($primaryPhone: String!, $message: MessageSchedulingJob!) {
  scheduleMessage(primaryPhone: $primaryPhone, message: $message) {
    id
    scheduledTime
    name
    account {
      ...AccountFragment
    }
    organization {
      ...OrganizationFragment
    }
    body
    media
    sentBy
    lists {
      ...ListFragment
    }
    totalMessages
    totalMessagesDelivered
    totalMessagesFailed
    type
  }
}

Variables

{
  "primaryPhone": "+15555554321",
  "message": MessageSchedulingJob
}

Response

{
  "data": {
    "scheduleMessage": {
      "id": 12345,
      "scheduledTime": "xyz789",
      "name": "Memorial Day Brick Sale",
      "account": Account,
      "organization": Organization,
      "body": "Hi {contact.first_name}, we're having a great sale on bricks this weekend.",
      "media": [
        [
          "https://example.com/image.png"
        ]
      ],
      "sentBy": "your.user@example.com",
      "lists": [List],
      "totalMessages": 100,
      "totalMessagesDelivered": 98,
      "totalMessagesFailed": 2,
      "type": "account"
    }
  }
}

Mutations

`scheduleWave`

Schedule a wave

Returns a Wave

Name	Description
`type` - `WaveType!`	Wave type (account/organization)
`primaryPhone` - `String`	Primary number on the Volt account (as shown in the interface)
`status` - `NewWaveStatus!`	Status of the wave (draft/scheduled, draft waves will not be processed)
`wave` - `WaveSchedulingJob!`	Other messaging information

Example

Query

mutation scheduleWave($type: WaveType!, $primaryPhone: String, $status: NewWaveStatus!, $wave: WaveSchedulingJob!) {
  scheduleWave(type: $type, primaryPhone: $primaryPhone, status: $status, wave: $wave) {
    id
    scheduledTime
    name
    account {
      ...AccountFragment
    }
    organization {
      ...OrganizationFragment
    }
    body
    media
    sentBy
    lists {
      ...ListFragment
    }
    totalMessages
    totalMessagesDelivered
    totalMessagesFailed
    type
  }
}

Variables

{
  "type": WaveType,
  "primaryPhone": "+15555554321",
  "status": NewWaveStatus,
  "wave": WaveSchedulingJob
}

Response

{
  "data": {
    "scheduleWave": {
      "id": 12345,
      "scheduledTime": "xyz789",
      "name": "Memorial Day Brick Sale",
      "account": Account,
      "organization": Organization,
      "body": "Hi {contact.first_name}, we're having a great sale on bricks this weekend.",
      "media": [
        [
          "https://example.com/image.png"
        ]
      ],
      "sentBy": "your.user@example.com",
      "lists": [List],
      "totalMessages": 100,
      "totalMessagesDelivered": 98,
      "totalMessagesFailed": 2,
      "type": "account"
    }
  }
}

Types

`Account`

Field Name	Description
`id` - `ID!`	ID of the account owning the phone number
`organization` - `Organization!`	Root organization to which the account is associated
`createdBy` - `String!`	Email of user who created the account
`name` - `String!`	Name of the account
`primaryPhone` - `String!`	Root phone number of the account (aside from numbers in pool if enabled)
`createdAt` - `String!`	Account creation date
`lastUpdatedAt` - `String!`	Time the organization was last updated
`callForwardingNumber` - `String`	Number to which a call to the primaryPhone or any phone in the pool is forwarded
`location` - `String`	Location of the entity this account represents

Example

{
  "id": 1234567,
  "organization": Organization,
  "createdBy": "your.user@example.com",
  "name": "Tulsa Store",
  "primaryPhone": "+15555554321",
  "createdAt": "2021-03-29T20:00:35.344134Z",
  "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
  "callForwardingNumber": "+15555551234",
  "location": "Tulsa, Oklahoma"
}

Types

`Boolean`

The Boolean scalar type represents true or false.

Example

true

Types

`Contact`

Field Name	Description
`id` - `ID!`	ID of the contact
`account` - `Account`	Account to which the contact is associated
`organization` - `Organization`	Root organization to which the contact is associated
`phoneNumber` - `String!`	Contact's receiving phone number
`name` - `String!`	Name of the contact
`mappedNumber` - `String`	Number the contact is mapped to if number pooling is enabled
`customFields` - `[ContactCustomField!]!`	Custom field values on the contact
`createdAt` - `String!`	Contact creation date
`lastUpdatedAt` - `String!`	Time the contact was last updated
`lists` - `[List!]!`	Lists to which this contact is a member
`blocked` - `Boolean!`	If the contact is blocked

Example

{
  "id": 1234,
  "account": Account,
  "organization": Organization,
  "phoneNumber": "+15555556893",
  "name": "Wile E. Coyote",
  "mappedNumber": "+15555551234",
  "customFields": [ContactCustomField],
  "createdAt": "2021-03-29T20:00:35.344134Z",
  "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
  "lists": [List],
  "blocked": false
}

Types

`ContactCustomField`

Field Name	Description
`key` - `String!`	Field name
`type` - `String!`	Field type
`value` - `String!`	Field value

Example

{
  "key": "species",
  "type": "string",
  "value": "Canis latrans"
}

Types

`ContactCustomFieldInput`

Input Field	Description
`key` - `String!`	Field name
`value` - `String!`	Field value

Example

{"key": "abc123", "value": "xyz789"}

Types

`Conversation`

Field Name	Description
`messages` - `[Message!]!`	Messages in conversation
`pageInfo` - `PageInfo!`	Paging information on conversation

Example

{
  "messages": [Message],
  "pageInfo": PageInfo
}

Types

`ID`

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example

object

Types

`Inbox`

Field Name	Description
`account` - `Account`	Account to which the contact is associated
`items` - `[InboxMessage!]!`	Inbox Items for the account
`pageInfo` - `PageInfo!`	Paging information on conversation

Example

{
  "account": Account,
  "items": [InboxMessage],
  "pageInfo": PageInfo
}

Types

`InboxMessage`

Field Name	Description
`contact` - `Contact`	Contact object for the message in inbox
`lastMessage` - `String!`	Last message content for the contact
`isUnread` - `Boolean!`	If the message is unread
`lastMessageTime` - `String!`	Timestamp of the last message

Example

{
  "contact": Contact,
  "lastMessage": "abc123",
  "isUnread": false,
  "lastMessageTime": "abc123"
}

Types

`Int`

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example

Types

`List`

Field Name	Description
`id` - `ID!`	ID of the list
`createdBy` - `String!`	Email of the user who created the list
`name` - `String!`	Name of the list
`createdAt` - `String!`	List creation date
`lastUpdatedAt` - `String!`	Time the list was last updated
`account` - `Account`	Account to which the list is associated
`size` - `Int!`	Number of contacts on this list
`querySourceListName` - `String`	The name of the list used as the basis for filtering based on a query; defaults to the All list
`queryNameSearchTerm` - `String`	Filters list contacts by name
`queryCustomFields` - `[ListQueryRule!]`	Filters list contacts by a rule

Example

{
  "id": 12345,
  "createdBy": "your.user@example.com",
  "name": "Loyal Customers",
  "createdAt": "2021-03-29T20:00:35.344134Z",
  "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
  "account": Account,
  "size": 542,
  "querySourceListName": "All",
  "queryNameSearchTerm": ,
  "queryCustomFields": [ListQueryRule]
}

Types

`ListQuery`

Outlines a query used in our contact center to define a list.

Input Field	Description
`listName` - `String!`	The name of the new list; must be unique per account
`querySourceListName` - `String`	The name of the list used as the basis for filtering based on a query
`queryNameSearchTerm` - `String`	Filters list contacts by name
`queryCustomFields` - `[ListQueryRuleInput!]`	Filters list contacts by a rule

Example

{
  "listName": "abc123",
  "querySourceListName": "abc123",
  "queryNameSearchTerm": "xyz789",
  "queryCustomFields": [ListQueryRuleInput]
}

Types

`ListQueryOperator`

An operator used for comparison during list filtering

Enum Value	Description
`gt`	Contact value is greater than the query rule value
`gte`	Contact value is greater than or equal to the query rule value
`lt`	Contact value is less than the query rule value
`lte`	Contact value is less than or equal to the query rule value
`eq`	Contact value is numerically equal to the query rule value
`bf`	Contact value is before the query rule value; valid for Dates
`af`	Contact value is after the query rule value; valid for Dates
`is`	Contact value is equivalent to the query rule value; valid for text
`has`	Contact value contains the query rule value; valid for text
`neq`	Contact value is not numerically equal to the query rule value
`nc`	Contact value does not contain the query rule value; valid for text

Types

`ListQueryRule`

Describes a filtering rule for a list query

Field Name	Description
`field` - `String!`	A custom dynamic field used in a query; should already be defined on an organization
`operator` - `ListQueryOperator!`	An operator used for comparison during filtering
`queryValue` - `String!`	The JSON-serialized value of a query field

Example

{
  "field": "purchases",
  "operator": ListQueryOperator,
  "queryValue": 5
}

Types

`ListQueryRuleInput`

Describes a filtering rule for a list query

Input Field	Description
`field` - `String!`	A custom dynamic field used in a query; should already be defined on an organization
`operator` - `ListQueryOperator!`	An operator used for comparison during filtering
`queryValue` - `String!`	The JSON-serialized value of a query field

Example

{
  "field": "abc123",
  "operator": ListQueryOperator,
  "queryValue": "abc123"
}

Types

`Message`

Field Name	Description
`id` - `ID!`	Volt assigned message ID
`legacyId` - `String!`	Provider assigned message ID
`account` - `Account`	Account from which the message originated
`organization` - `Organization`	Organization from which the message originated
`toNumber` - `String!`	Number to which the message was sent
`fromNumber` - `String!`	Number from which the message originated
`status` - `String!`	Message status (failed, sending, sent, or delivered)
`statusDescription` - `String!`	Detailed description associated with message status
`media` - `[String!]!`	Media sent with the message
`body` - `String!`	Message body
`sentAt` - `String!`	Time the message was sent to provider
`confirmedAt` - `String!`	Time message status was confirmed by provider
`wave` - `Wave`	Wave from which the message originated
`contact` - `Contact`	Contact on the receiving end of the message
`errorCode` - `String`	Error code associated with message failure (if applicable)

Example

{
  "id": rf_1234abcd,
  "legacyId": "40317653-15ed-444e-b232-98933f63adf8",
  "account": Account,
  "organization": Organization,
  "toNumber": "+15555556893",
  "fromNumber": "+15555556894",
  "status": "received",
  "statusDescription": "Incoming message received",
  "media": [
    "https://example.com/image.png"
  ],
  "body": "Well, back to the old drawing board.",
  "sentAt": "2021-03-29T20:00:35.344134Z",
  "confirmedAt": "2021-03-29T20:00:35.344134Z",
  "wave": Wave,
  "contact": Contact,
  "errorCode": "abc123"
}

Types

`MessageSchedulingJob`

Input Field	Description
`scheduledTime` - `String!`	Time the message will be sent in UTC (YYYY-MM-DD HH:MM:SS)
`messageBody` - `String!`	Body of the message
`contactNumbers` - `[String!]!`	Contacts associated with the message
`media` - `[String!]`	Media to be sent with the message

Example

{
  "scheduledTime": "abc123",
  "messageBody": "xyz789",
  "contactNumbers": ["abc123"],
  "media": ["xyz789"]
}

Types

`NewWaveStatus`

Enum Value	Description
`draft`	Signifies a draft wave
`scheduled`	Signifies a scheduled wave

Types

`Organization`

Field Name	Description
`id` - `ID!`	ID of the organization tied to the access token
`companyName` - `String!`	Name of the organization that owns the phone numbers used in messaging
`domain` - `String`	Web domain of the organization
`size` - `String`	Organization size as input during onboarding
`industry` - `String`	Organization industry as input during onboarding
`createdAt` - `String!`	Organization creation date
`lastUpdatedAt` - `String!`	Time the organization was last updated
`isOnFreeTrial` - `Boolean!`	If the organization is on a free trial
`isActive` - `Boolean!`	If the organization is active (has not submit disabling request)

Example

{
  "id": 1234567,
  "companyName": "Acme Corporation",
  "domain": "example.com",
  "size": "11-50",
  "industry": "Retail",
  "createdAt": "2021-03-29T20:00:35.344134Z",
  "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
  "isOnFreeTrial": false,
  "isActive": true
}

Types

`PageInfo`

Field Name	Description
`totalItems` - `Int!`	Total items in set
`nextPage` - `String`	Next page cursor
`hasNextPage` - `Boolean!`	If the set has a next page

Example

{"totalItems": 123, "nextPage": "xyz789", "hasNextPage": true}

Types

`String`

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Types

`Wave`

Field Name	Description
`id` - `ID!`	ID of the wave
`scheduledTime` - `String!`	Time the wave is scheduled to begin processing
`name` - `String!`	Name of the wave
`account` - `Account`	Account from which the wave originated
`organization` - `Organization`	Root organization from which the wave originiated
`body` - `String!`	Message body
`media` - `[String!]!`	Associated media
`sentBy` - `String!`	Sending user
`lists` - `[List!]`	Lists included in the wave
`totalMessages` - `Int!`	Total message in the wave
`totalMessagesDelivered` - `Int!`	Total messages delivered
`totalMessagesFailed` - `Int!`	Total messages failed
`type` - `String!`	Wave type (one of contact, account, or group)

Example

{
  "id": 12345,
  "scheduledTime": "xyz789",
  "name": "Memorial Day Brick Sale",
  "account": Account,
  "organization": Organization,
  "body": "Hi {contact.first_name}, we're having a great sale on bricks this weekend.",
  "media": [
    "https://example.com/image.png"
  ],
  "sentBy": "your.user@example.com",
  "lists": [List],
  "totalMessages": 100,
  "totalMessagesDelivered": 98,
  "totalMessagesFailed": 2,
  "type": "account"
}

Types

`WaveSchedulingJob`

Field Name	Description
`waveName` - `String!`	Name of the wave
`scheduledTime` - `String!`	Time the wave will be sent in UTC (YYYY-MM-DD HH:MM:SS)
`messageBody` - `String!`	Body of the wave
`listNames` - `[String!]!`	Lists involved in the wave
`media` - `[String]`	Media associated with the wave

Example

{
  "waveName": "abc123",
  "scheduledTime": "xyz789",
  "messageBody": "abc123",
  "listNames": ["abc123"],
  "media": ["abc123"]
}

Types

`WaveType`

Enum Value	Description
`account`	Signifies an account wave
`organization`	Signifies a group wave

Types

`Webhook`

Field Name	Description
`id` - `ID!`	Webhook ID
`organization` - `Organization!`	Root organization to which this webhook is associated
`url` - `String!`	Webhook destination URL
`createdAt` - `String!`	Webhook creation date
`lastUpdatedAt` - `String!`	Time the webhook was last updated
`primaryPhone` - `String`	Root phone number of a specific account with which webhook is registered; defaults to all if not specified
`eventTypes` - `[WebhookEventType!]`	A list of events that will trigger a webhook; requires `primaryPhone` to be specified; defaults to all

Example

{
  "id": 1234,
  "organization": Organization,
  "url": "https://example.com/webhook",
  "createdAt": "2021-03-29T20:00:35.344134Z",
  "lastUpdatedAt": "2021-03-29T20:00:35.344134Z",
  "primaryPhone": "+15555556893",
  "eventTypes": [WebhookEventType]
}

Types

`WebhookEventType`

An event that a webhook can be configured to receive

Enum Value	Description
`MESSAGE_RECEIVED`	An event triggered by an inbound message
`MESSAGE_FINALIZED`	An event triggered by a delivery or failure receipt from a carrier
`MESSAGE_SENT`	An event triggered when a message is sent to a carrier
`CALL_INITIATED`	An event triggered when an inbound phone call begins (only applicable with call forwarding)
`CALL_HANGUP`	An event triggered when an inbound phone call ends (only applicable with call forwarding)