API quickstart

This quickstart takes you from an empty integration to a first WhatsApp message sent through the API. You need a Shortext company with at least one connected WhatsApp number.

Create an API key

In the dashboard, open Developer > API Keys and create a key. Give it a name (for example “CRM integration”) and choose its permissions. To follow this quickstart, keep Send messages checked; add Manage integrations if your integration also manages agents, channels or webhooks.The key is shown once. Store it in a secret manager or an environment variable, for example SHORTEXT_API_KEY.

An API key gives access to your company’s data. Never put it in a mobile app, a web page or a public repository.

Check the key with GET /me

Every request sends the key as a bearer token. GET /me tells you which company and which key you are using.

curl https://shortext.ny-corp.io/api/v2.0/me \
  -H "Authorization: Bearer $SHORTEXT_API_KEY" \
  -H "Accept: application/json"

<?php
$response = (new GuzzleHttp\Client())->get('https://shortext.ny-corp.io/api/v2.0/me', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('SHORTEXT_API_KEY'),
        'Accept'        => 'application/json',
    ],
]);

$result = json_decode((string) $response->getBody(), true);
if (!$result['success']) {
    throw new RuntimeException("Shortext error {$result['code']}: {$result['message']}");
}
echo $result['body']['company']['name'];

const response = await fetch("https://shortext.ny-corp.io/api/v2.0/me", {
  headers: {
    Authorization: `Bearer ${process.env.SHORTEXT_API_KEY}`,
    Accept: "application/json",
  },
});

const result = await response.json();
if (!result.success) {
  throw new Error(`Shortext error ${result.code}: ${result.message}`);
}
console.log(result.body.company.name);

import os
import requests

response = requests.get(
    "https://shortext.ny-corp.io/api/v2.0/me",
    headers={
        "Authorization": f"Bearer {os.environ['SHORTEXT_API_KEY']}",
        "Accept": "application/json",
    },
)

result = response.json()
if not result["success"]:
    raise RuntimeError(f"Shortext error {result['code']}: {result['message']}")
print(result["body"]["company"]["name"])

Response

{
  "success": true,
  "message": "Request success.",
  "code": 1000,
  "body": {
    "company": { "id": "CMP-XXXXX", "name": "Acme" },
    "user": null,
    "token": {
      "name": "CRM integration",
      "abilities": ["permissions.send_messages", "permissions.view_messages"],
      "last_used_at": "2026-10-24T09:12:44.000000Z",
      "expires_at": null
    },
    "api_version": "v2.0"
  }
}

The HTTP status is always 200: read success and code to know the outcome. See API introduction.

Find your channel and a template

GET /channels?type=whatsapp lists your WhatsApp numbers. The id of a channel is the channel_id you send messages from.WhatsApp only lets a business write first with an approved template. GET /templates?channel_id={id}&status=APPROVED lists the templates this number can send, with their variables.

Send your first message

POST /conversations sends a first message to a contact and opens (or continues) the conversation.

curl -X POST https://shortext.ny-corp.io/api/v2.0/conversations \
  -H "Authorization: Bearer $SHORTEXT_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "channel_id": "532867649916076",
    "contact": {
      "identifier": "237699999999",
      "profile": { "firstname": "Brice", "lastname": "Mbarga", "preferred_language": "fr" }
    },
    "message": {
      "type": "template",
      "content": {
        "template_name": "order_update",
        "language": "fr",
        "body": { "name": "Brice", "order": "A-1042" }
      }
    }
  }'

<?php
$response = (new GuzzleHttp\Client())->post('https://shortext.ny-corp.io/api/v2.0/conversations', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('SHORTEXT_API_KEY'),
        'Accept'        => 'application/json',
    ],
    'json' => [
        'channel'    => 'whatsapp',
        'channel_id' => '532867649916076',
        'contact'    => [
            'identifier' => '237699999999',
            'profile'    => ['firstname' => 'Brice', 'lastname' => 'Mbarga', 'preferred_language' => 'fr'],
        ],
        'message'    => [
            'type'    => 'template',
            'content' => [
                'template_name' => 'order_update',
                'language'      => 'fr',
                'body'          => ['name' => 'Brice', 'order' => 'A-1042'],
            ],
        ],
    ],
]);

$result = json_decode((string) $response->getBody(), true);
if (!$result['success']) {
    throw new RuntimeException("Shortext error {$result['code']}: {$result['message']}");
}
$conversationId = $result['body']['conversation']['id'];

const response = await fetch("https://shortext.ny-corp.io/api/v2.0/conversations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SHORTEXT_API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    channel_id: "532867649916076",
    contact: {
      identifier: "237699999999",
      profile: { firstname: "Brice", lastname: "Mbarga", preferred_language: "fr" },
    },
    message: {
      type: "template",
      content: {
        template_name: "order_update",
        language: "fr",
        body: { name: "Brice", order: "A-1042" },
      },
    },
  }),
});

const result = await response.json();
if (!result.success) {
  throw new Error(`Shortext error ${result.code}: ${result.message}`);
}
const conversationId = result.body.conversation.id;

import os
import requests

response = requests.post(
    "https://shortext.ny-corp.io/api/v2.0/conversations",
    headers={
        "Authorization": f"Bearer {os.environ['SHORTEXT_API_KEY']}",
        "Accept": "application/json",
    },
    json={
        "channel": "whatsapp",
        "channel_id": "532867649916076",
        "contact": {
            "identifier": "237699999999",
            "profile": {"firstname": "Brice", "lastname": "Mbarga", "preferred_language": "fr"},
        },
        "message": {
            "type": "template",
            "content": {
                "template_name": "order_update",
                "language": "fr",
                "body": {"name": "Brice", "order": "A-1042"},
            },
        },
    },
)

result = response.json()
if not result["success"]:
    raise RuntimeError(f"Shortext error {result['code']}: {result['message']}")
conversation_id = result["body"]["conversation"]["id"]

The response holds the conversation and the sent message. Keep conversation.id: you use it to reply, take the conversation over or read its messages.

Receive the replies

When the contact answers, the agent attached to the channel replies automatically. To follow the conversation from your system, create a webhook endpoint subscribed to message.*.

Next steps

Authentication

API keys and their permissions.

Message format

Text, templates, interactive messages and media.

Webhooks

Receive signed events in real time.

The 24-hour rule

When WhatsApp accepts free text, and when it needs a template.

Introduction

Getting started

Agents

Channels

Inbox

Next steps

Authentication

Message format

Webhooks

The 24-hour rule

​Next steps

Authentication

Message format

Webhooks

The 24-hour rule

Next steps