Introduction to SuperPhone’s API

Introduction

SuperPhone’s API allows you to build a fully custom SMS marketing system in the easiest way imaginable. You won’t need to worry about all the regulations that make building a scalable SMS ecosystem so hard to do — SuperPhone handles all of this already.

SuperPhone’s API uses an API key for authentication and GraphQL as the base. In this tutorial we’ll show you how to use the API and how you can do simple REST POST requests you’re familiar to retrieve data from SuperPhone.

Features

We constantly add features to our Public API with the goal of offering everything that’s on our private API on the Public API. So there might be more features available than we have listed here. For everything available please read our documentation. We also make sure to add every feature in a user friendly way to our Zapier integration.

As of this writing our API allows for:

• Retrieving information about a single contact
• Retrieving a list of contacts (as shown in this tutorial)
• Retrieving a contact by their email or phone number
• Retrieving all messages in a conversation
• Retrieving a list of conversations
• Retrieving the current configuration of your default form
• Retrieving the current configuration of any form
• Retrieving a list of forms
• Retrieving a list of webhooks linked to your account
• Creation of contacts
• Updating contacts
• Adding custom contributions
• Updating a custom contribution
• Removing a custom contribution
• Adding tags to contacts, either by tag name or tag ID
• Removing tags from a contact, either by tag name or tag ID
• Sending a message (as shown in this tutorial)
• Creating a form
• Updating a form
• Disabling a form
• Enabling a form
• Creating Webhooks for:
• Contact added events
• Contact updated events
• Contact tags changed events
• Message received events
• Message sent events
• Updating a Webhook

The API Key

The API key can be found on the settings page of your SuperPhone account, towards the bottom. Here’s a direct link:

https://app.superphone.io/settings/public-api-key

When you first get started you need to generate an API key. You can always come back here to revoke or regenerate it. You’ll also find a link to our documentation on this page. In order to copy the API key, just click the copy icon next to it:

API Explorer

Before implementing the API into your system, you can use our API explorer to test API calls you’ll eventually want to use. The explorer can be found here:

https://api.superphone.io/explorer

To get started, paste the API key at the top:

Now we’re ready to write some requests. In GraphQL searches are called queries and actions are called mutations. To find out more about GraphQL, feel free to check out the numerous articles online, like this one: https://graphql.org/learn/

We’ll start by writing a request to get the latest 10 contacts:

‍

‍

query getContacts {
 contacts(last: 10) {
   total
   nodes {
     id
     vip
     firstName
     lastName
     email
     mobile
     tags(first: 10) {
       nodes {
         id
         name
       }
     }
   }
 }
}

‍

Tip: Pressing ctrl + space will present you with the options you have throughout the explorer.

Let’s run the query and see what happens:

Great — this worked! Now let’s send our first message to me, the writer of this article to let me know you’re trying out the API:

mutation sendMessage {
 sendMessage(input: {
   mobile: "213–267–9977",
   platform: TWILIO,
   body: "Hey Flo, I'm testing the API!"
 }) {
   message {
     id
   }
   sendMessageUserErrors {
     field
     message
   }
 }
}

‍

Note: ideally you always send the phone number in E.164 format, including the country code. For example: +12132679977. If you don’t use this format, SuperPhone will try to detect the format you’re sending and if there’s no country code, it will default to US. So if you’re texting internationally, it’s best to use E.164.

‍

Let’s run the mutation and see what happens:

‍

Great, I’ve just received your text (or whoever you texted 🙂)

Sending GraphQL requests in a REST POST request

We get this question all the time — How do I actually send and implement this? While there’s a lot of frameworks out there, and probably one that fits your system, there’s also the common way of using simple REST POST requests. Here’s how that works in Postman:

First, pick POST at the top left, set the endpoint to https://api.superphone.io/graphql and then setup the headers:

Accept: application/json

Content-Type: application/json

Authorization: Bearer <API Key>

It should look like this:

Finally we setup the body as Raw JSON like this:

And that’s it — Now you can run the query as a regular POST request.

If there’s something I can help you with or you are missing feature, please don’t hesitate to shoot me a text on my SuperPhone at +1 (213)-267–9977 or at flopmt.com!

‍