Statflo Documentation

GraphQL

GraphQL

TextKit has been designed from the ground-up to be powered by GraphQL. It provides a single endpoint for you to read from or communicate with TextKit.

When you register with TextKit, we supply you with an assigned endpoint:

http://path.to.your.textkit.instance/graphql

You'll need to provide an Authorization header with your request. The type of Authorization (token, etc) will depend on how you have configured TextKit with us (embedded, hosted, or enterprise).

Queries

Queries are used to GET a result from TextKit, such as a status, list of campaigns, activity report or list of templates.

While we recommend that all requests in GraphQL are done via POST, you can also use a GET request, in this format:

GET http://myapi/graphql?query={getCampaigns{campaigns{id}}}

If a query requires variables, they can be sent as an encoded string in an additional query parameter called variables.

GET http://myapi/graphql?query=%7BgetCampaigns%7Bcampaigns%7Bid%7D%7D%7D&variables=%7B%22id%22%3A%20%22someValue%22%7D

To make a query using POST, use the application/json content type, and include a JSON-encoded body like this:

{
"query": "query aTest($arg1: String!) { test(who: $arg1) }",
"operationName": "aTest",
"variables": { "arg1": "me" }
}

You can batch requests together as well:

mutation {
getCampaign(input: {
id: "455393a5-1b43-40ac-8562-68c0ce94a79d"
}) {
campaign {
name
startDate
}
},
getCampaign(input: {
id: "1e100522-dfb4-42d9-8edf-5738f3f86790"
}) {
campaign {
name
}
}
}

Which would return:

{
"data": {
"getCampaign": {
"name": "Loan Follow-Up",
"startDate": "2021-01-14T010:00:00Z"
},
"getCampaign": {
"name": "Account Activation"
}
}
}

Mutations

Mutations let you make changes to your TextKit configuration or your TextKit data. These are the equivalent of POST, PUT or DELETE methods of a typical REST API. All mutations must be made using a POST request.

mutation {
createCampaign(input: {
name: "Loan Follow-Up"
description: "Customers who recently got new loan."
startDate: "2021-01-03T010:00:00Z"
endDate: "2021-02-03T010:00:00Z"
state: DRAFT
}) {
userErrors {
field
message
}
campaign {
id
}
}
}

Mutations always have a name, and a structure to them. Not all fields are always required, and so you simple pass along the ones that are. You can also request to get certain results back, such as a certain field.

The above responses with this, since we specifically asked for the id field:

{
"data": {
"createCampaign": {
"id": "455393a5-1b43-40ac-8562-68c0ce94a79d"
}
}
}

One of the great things about GraphQL is you don't have to make multiple API requests to get the data you need. You can chain requests together, only provide what is required (and what else you want to send). You can also get a result that only gives you back what you need, and nothing else.

This makes GraphQL a great choice for interfaces, and for control of what data fields can be accessed by what users. If an authorization token does not have the permission to see a field based on their role, GraphQL will not let them request it. When building interfaces, such as a Widget, you can make a request for only what the Widget needs.

mutation {
createCampaign(input: {
name: "Loan Follow-Up"
description: "Customers who recently got new loan."
startDate: "2021-01-03T010:00:00Z"
endDate: "2021-02-03T010:00:00Z"
state: DRAFT
}),
createCampaignMember(input: {
firstName: "Hans"
from: "+15551112323"
to: "+14443336666"
method: SMS
assignedUserId: "af73ed10-01ff-4b96-8444-079ff8fdda57"
locale: "EN_US"
state: INACTIVE
})

Which returns:

{
"data": {
"createCampaign": "455393a5-1b43-40ac-8562-68c0ce94a79d",
"createCampaignMember": "dbee7e46-a486-4d8c-b494-5adf04d5cab3"
}
}

Learning

Some good resources to help you see the core concepts of GraphQL:

Learning: https://graphql.org/learn/

7-min Intro Video (The Net Ninja) - there's a whole series here

GraphQL Libraries: