Welcome to Superchat! This guide will help you send messages to your customers across multiple channels – WhatsApp, SMS, Email, and Instagram – using Superchat’s unified REST API.

We’ll walk you through the basics of authenticating with the API, using the /messages endpoint, channel-specific requirements, message types, and best practices for managing contacts.

By the end, you’ll be able to integrate Superchat into your application and send your first messages in just a few steps.

API Basics and Authentication

Superchat’s API provides a single endpoint to send messages across all connected platforms. In other words, whether you want to send a WhatsApp message, an SMS, an email, or reply on Instagram, you’ll use the same HTTP endpoint: POST /messages. This unified approach makes it easy to integrate once and communicate everywhere.

Authentication: All API requests require your Superchat API key for security. You can find your API key in the Superchat dashboard under Settings > Integrations > API Key. Include this key in an HTTP header (X-API-KEY) for each request.

Making a Request: To send a message, you will make an HTTP POST request to the /messages endpoint (e.g. https://api.superchat.com/v1.0/messages). In the request body, you will specify:

• from – the sender information, i.e. which of your channels the message should come from (for example, your WhatsApp business number, SMS number, email identity, etc.). This is identified by a channel ID in your Superchat account.
• to – the recipient information. You can either use an existing contact’s ID, or provide a new identifier (like a phone number or email). If you provide a new phone number or email here, Superchat will automatically create a new contact for you if one doesn’t exist. Please make sure to format your phone numbers in E164 format.
• content – the content of the message, which varies based on the type field inside the content object.

Every message you send via Superchat will create or use a contact in your Superchat workspace. If you send to a new phone number/email that isn’t in your contacts yet, the API will create a contact entry automatically and return its ID in the response. You can then use this contact ID to update the contact’s details.

Channel-Specific Guidelines

Each messaging channel has some unique rules or behaviors. Superchat abstracts away a lot of complexity with the unified /messages endpoint, but it’s important to understand the key differences for each channel:

WhatsApp

• 24-Hour Messaging Window: WhatsApp enforces a customer care window of 24 hours for free-form messages. If a customer sends you a message, you have 24 hours to reply with any content. Outside that 24-hour window, or if you’re messaging a customer first, you must use a pre-approved WhatsApp Template message. Standard text messages will not be delivered outside the 24-hour window and throw an error on send.

• Templates for Out-of-Window Messages: WhatsApp templates are pre-approved message formats. Superchat supports sending these templates via the API. Each template has a name, a language, and optionally variables/placeholders that you can fill in. For example, you might have a template like “Order Shipped” with a placeholder for the customer’s name or order number. You’ll specify the template ID and supply the variable values when sending. Once a template is approved in Superchat, it can be sent at any time, even outside the 24h window.

• Template Variables: When using a WhatsApp template, you can include variables in the template body that get replaced with dynamic content (like names, order IDs, dates, etc.). Superchat’s API allows you to pass an array of values for these placeholders when sending the template. This way, you can personalise each message. WhatsApp templates may also include media attachments or interactive components, but to start, text with placeholders is most common.

ℹ️

Use WhatsApp templates to initiate conversations

If the last user message was more than 24 hours ago (or if you are contacting them for the first time), you must use a WhatsApp template to initiate the conversation. Regular WhatsApp messages will not go through outside the 24-hour window.

Instagram and Facebook Messenger

• No New Outbound Messages: Due to Instagram’s messaging policies, you cannot send the first message to a user on Instagram via the API. In other words, outbound Instagram messages are only allowed as replies to an inbound message from the user. If a customer sends your business an Instagram Direct Message, you can reply within a 7 day window. But you cannot initiate a conversation with a user who hasn’t messaged you first.

• Instagram and Facebook Messenger currently allow a 7-day conversation window after each inbound message. This means once a user messages you on Instagram, you have up to 7 days to send replies. After that window closes, you won’t be able to send additional messages until the user messages you again.

SMS and Email

• No Conversation Window Restrictions: Unlike WhatsApp or Instagram, SMS and Email have no built-in time window rules. You can send messages to your customers via SMS or email at any time, as long as you have their correct phone number or email address and appropriate consent.

• SMS Messages: For SMS, simply ensure you have the recipient’s mobile number (again, using international format is a good practice for global deliverability). SMS messages can only contain text content or links. If you need to send images or files, those would typically be sent via MMS or other channels, but Superchat treats SMS as text-only. The API will accept a plain text body and deliver it as an SMS.

• Email Messages: To send an email via the Superchat API, you will provide the recipient’s email address and your connected email channel. The content of an email message usually includes a subject and a body.

Message Content Types (type field)

When sending a message, the request JSON includes a field (commonly named type) that tells Superchat what kind of message you are sending. This determines what the content should look like. Here are the most common types:

• text – A plain text message. Use this for simple messages across any channel (SMS text, WhatsApp text, etc.). The content would typically include a "text": "<your message text>" field in this case.

• whats_app_template – A WhatsApp Template Message. Use this when sending a pre-approved template on WhatsApp. The content needs to include template details (like the template name or ID, language code, and an array of parameters for the template placeholders). See the example below for the structure.

• file – A file or media message. This is used when you want to send an attachment (image, document, etc.). Before sending a file message, you usually need to upload the file via the API to get a file ID. Then, in the message request, you’d provide the file ID or URL. The content might look like "file": { "id": "<file-id>" } or similar, depending on the API. Superchat supports media messages on all channels that allow media (e.g. WhatsApp images, email attachments, etc.).

• email – An email message. This type would be used if the API expects a distinction for email. Content would include email-specific fields like subject and body. (In some cases, the API might infer from the channel that it’s an email and use a text type with subject included separately. But conceptually, email is a distinct content type because of the subject line.)

• Other types: Superchat’s unified messaging also supports some channel-specific interactive message types. For example, on WhatsApp you might see types like quick replies or lists (whats_app_quick_reply, whats_app_list), or buttons on live chat. These are more advanced and optional. In this getting-started guide, we’ll focus on the basics like text, templates, and files. (If you’re interested, the Superchat documentation covers these additional types in detail.)

No matter the type, Superchat’s API ensures that if the target channel supports that content, it will be delivered appropriately. For instance, a text type will be sent as an SMS text if the channel is SMS, or as a WhatsApp message if the channel is WhatsApp, etc.. The goal is to make sending messages consistent across channels.

Best Practice: Contact Creation and Updating

One convenient feature of the Superchat API is that you don’t have to manually create a contact before sending a message. If you send a message to a new phone number or email that isn’t already in your contacts, Superchat will automatically create a new contact entry for you (and return its details in the response). This saves time during integration – you can just fire the message, and the contact appears in your system.

However, after that first message, you might want to enrich or update the contact’s information in your database. For example, you might want to add the contact’s name, customer ID from your system, or other custom attributes.

Note: It’s a best practice to use the contact ID returned from the message response to update the contact’s info. For instance, after sending a message to +15550123456, you’ll receive a contact_id (or a full contact object) in the API response. You can then call the Update Contact endpoint (PATCH /contacts/{contact_id}) to add details like the contact’s name, or set custom attributes (e.g. customer_type = "VIP", preferred_language = "EN", etc.). By doing this, you ensure your contact list in Superchat stays organized and enriched with any data you have from your own system.

To update a contact’s attributes, you’ll make a PATCH request to the contact’s endpoint. In the body, include any fields or custom attributes you want to change. (Note: Custom attributes need to be created in Superchat beforehand if they don’t already exist. You can create and manage custom contact fields via the API or dashboard.)

Keeping contact info up-to-date is optional for sending messages (you can always send just with a number/email), but it’s very useful for context. For example, you could store a customer ID or a CRM link as a custom attribute on the Superchat contact so that all your systems reference the same customer.

Examples

Let’s put it all together with some concrete examples. Below are sample API requests (shown as curl commands with JSON data) for common messaging scenarios. In these examples, replace YOUR_API_KEY, IDs, and sample content with your actual values.

Example 1: Sending a WhatsApp Template Message

Imagine you want to send a shipping notification to a customer on WhatsApp using a template called "OrderShipped". This template has two placeholders: {1} = customer name, and {2} = order number. Here’s how you can send it via the API:

curl --request POST \
     --url https://api.superchat.com/v1.0/messages \
     --header "X-API-KEY: YOUR_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{
  "to": [ { "identifier": "+15550123456" } ],
  "from": { "channel_id": "mc_whatsapp_001" },
  "content": {
    "type": "whats_app_template",
    "template_id": "template_id",
    "variables": [
      { "position": 1, "value": "John Doe" },
      { "position": 2, "value": "12345" }
    ]
  }
}'

What’s happening here? We specify the WhatsApp channel in the from.channel_id (you can fetch this id from the GET /channels endpoint). The to[0].phone_number is the customer’s number in E.164 format. We set "type": "whats_app_template" to indicate this is a WhatsApp template message. In content, we provide the template_id, and we fill in the template’s placeholders via the variables array. In this case, we assume the template’s body text has two variables (name and order). The API will send this template message through WhatsApp. If the template is not yet approved or the placeholders don’t match the template format, you would get an error, so ensure your template and variables are correct.

Example 2: Sending a Standard SMS Text Message

Now let’s send a simple SMS. Say you want to send a reminder to a customer’s phone number:

curl --request POST \
     --url https://api.superchat.com/v1.0/messages \
     --header "X-API-KEY: YOUR_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{
  "to": [ { "identifier": "+15551231234" } ],
  "from": { "channel_id": "mc_sms_002" },
  "content": {
    "type": "text",
    "text": "Reminder: your appointment is tomorrow at 10 AM."
  }
}'

Here, the from.channel_id would be the ID of your SMS sending number/identity as configured in Superchat. We use the recipient’s phone number in international format. The type is "text", and we provide a "text" field in the content with the message. The Superchat API will route this as an SMS. There’s no subject or fancy formatting – just the text content. The API response will contain a message ID and likely the contact ID for the recipient. If the contact +15551231234 didn’t exist before, it will be created automatically. You can now update that contact with a name or any contact attributes if needed (see Example 5).

Example 3: Sending an Email Message

Let’s send an email through the API. Suppose you have an email channel connected (like [email protected]) and want to send an email to a customer:

curl --request POST \
     --url https://api.superchat.com/v1.0/messages \
     --header "X-API-KEY: YOUR_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{
  "to": [ { "identifier": "[email protected]" } ],
  "from": { "channel_id": "mc_email_003" },
  "content": {
    "type": "email",
    "subject": "Your Order Update",
    "text": "Hi Alice,\n\nYour order has shipped!\n\nThanks."
  }
}'

In this JSON, from.channel_id is your email sending identity’s ID. The to[0].email is the customer’s email address. We set "type": "email" to clarify we’re sending an email. In the content, we include a subject line and the body text. Here we use a plain text body (with newline characters for formatting), but you could also include an HTML version. When this API call is made, Superchat will send an email to the customer via your configured email channel. The response will contain a conversation ID, message ID and contact ID just like with other channels. (Again, if [email protected] wasn’t an existing contact, a new contact is created for that email.)

Example 4: Replying to an Instagram Message

Now, assume a customer sent you a message on Instagram (perhaps to your business’s Instagram Direct Inbox) and you want to reply via the API. You have the contact ID for Instagram user who sent the inbound message (Superchat would have delivered this to you via webhook). Let’s say the contact ID was co_123, and your Instagram channel ID is mc_123. Here’s how to reply:

curl --request POST \
     --url https://api.superchat.com/v1.0/messages \
     --header "X-API-KEY: YOUR_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{
  "to": [ { "identifier": "ct_123" } ],
  "from": { "channel_id": "mc_123" },
  "content": {
    "type": "text",
    "text": "Thanks for reaching out – we’ll get back to you shortly!",
  }
}'

Let’s unpack that: from.channel_id is your Instagram channel/page identifier (the source of the message). For to, in this case we use an "id" for the contact. When the customer first messaged you on Instagram, Superchat created a contact for that Instagram user (or used an existing one if somehow matched). You can use that contact’s ID here to ensure the message goes to the right conversation. The type is "text" because we’re just sending a text reply.

Example 5: Updating Contact Attributes after Sending a Message

After sending out messages, you’ll want to update your contacts with any additional info you have. Using the contact ID from the message response, you can update the contact’s name or custom attributes. For instance, suppose in Example 2 (SMS) the API response returned a contact with id: "ct_789xyz" for the phone number +15551231234. We can now do:

curl --request PATCH \
     --url https://api.superchat.com/v1.0/contacts/ct_789xyz \
     --header "X-API-KEY: YOUR_API_KEY" \
     --header "Content-Type: application/json" \
     --data '
{
  "first_name": "Karla",
  "custom_attributes": [
    {
      "id": "cat_1234",
      "value": "CUST-123456"
    },
    {
      "id": "cat_3930",
      "value": "SMS"
    }
  ]
}'

This call updates the contact ct_789xyz with a first name, and two custom attributes: a customer ID (perhaps from our internal database) and a preferred channel. For both contact attributes the Superchat contact attribute ID is used.

A few notes on this:

• You do not need to update contacts to continue messaging them, but it’s helpful for record-keeping.
• Custom attributes allow you to store arbitrary data about the contact (like subscription status, customer segment, etc.). You can create custom attributes in Superchat (via API or the web app) and then set their values via the API as shown.
• The PATCH /contacts/{id} endpoint only needs the fields you want to update. Fields not included will remain unchanged. In the above example, we didn’t specify anything about phone or email in the PATCH, so those remain as they were; we just added/updated the name and custom fields.
• If you would like to add a new contact handle to contact such as another phone number or email address, make sure that this handle is not used with another contact as this would fail the update operation.

That’s it! You’ve now learned how to send messages through Superchat’s API across different channels and how to handle contacts. For more detailed information on each endpoint and advanced features, check out the Superchat API Reference – it covers things like message status webhooks, more message types, error handling, and more. We hope this guide helps you get up and running quickly.

Happy messaging!