Hosted sessions

A hosted session is a signed, expiring link to a page hosted by Shortext, where your user completes a step you cannot do in your own product: logging in to Meta to connect a WhatsApp Business number, entering and checking mailbox settings, or writing a WhatsApp template in the Shortext editor. When they are done, they come back to your app and you receive the result. Typical case: you build a product on Shortext, and each of your clients connects their own WhatsApp number to the agent you set up for them.

Flow

Create the session (your server)

POST /hosted-sessions with a purpose. The response holds the url of the page.

Send your user to the page

Redirect them, or open the URL in a new window. Do not embed it in an iframe: the Meta login refuses it.

Your user completes the page

On https://shortext.ny-corp.io/connect/{token}, they log in to Meta or fill in their mailbox settings.

Back to your app

Shortext sends them to your return_url with ?session_id={id}&status={status}.

Get the result (your server)

Receive the hosted_session.completed or hosted_session.failed webhook, or call GET /hosted-sessions/{id}. Do not trust the status of the return URL alone: anyone can type it.

Purposes

GET /hosted-sessions/purposes lists them.

Purpose	Page	`context`
`whatsapp`	Connect WhatsApp Business numbers with Meta embedded signup.	`agent_id`: the agent that answers on the numbers (default: your first agent).
`mail`	Connect a mailbox with IMAP / SMTP; the connection is checked before saving.	`agent_id`: the agent that answers on the mailbox (default: your first agent).
`template`	Write a WhatsApp template in the Shortext editor and submit it to Meta.	`channel_id` (required): a WhatsApp number, whose WhatsApp Business account owns the template. Optional: `name`, `category` (`MARKETING`, `UTILITY`, `AUTHENTICATION`), `language`, to prefill the editor.

Create a session

Requires the Manage integrations permission.

string

required

whatsapp, mail or template.

object

Options of the purpose, for example { "agent_id": "AGI-XXXXX" }. The agent must belong to your company.

string

Your page the user comes back to. HTTPS only.

string

The language of the page, for example fr or en.

integer

default:"60"

Lifetime of the link in minutes, from 5 to 1,440 (24 hours).

curl -X POST https://shortext.ny-corp.io/api/v2.0/hosted-sessions \
  -H "Authorization: Bearer $SHORTEXT_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "whatsapp",
    "context": { "agent_id": "AGI-XXXXX" },
    "return_url": "https://app.example.com/settings/whatsapp",
    "locale": "fr",
    "expires_in": 60
  }'

<?php
$response = (new GuzzleHttp\Client())->post('https://shortext.ny-corp.io/api/v2.0/hosted-sessions', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('SHORTEXT_API_KEY'), 'Accept' => 'application/json'],
    'json'    => [
        'purpose'    => 'whatsapp',
        'context'    => ['agent_id' => 'AGI-XXXXX'],
        'return_url' => 'https://app.example.com/settings/whatsapp',
        'locale'     => 'fr',
        'expires_in' => 60,
    ],
]);
$session = json_decode((string) $response->getBody(), true)['body'];

// Store $session['id'], then send the user to the page (never log the URL: it holds a secret)
header('Location: ' . $session['url']);

const response = await fetch("https://shortext.ny-corp.io/api/v2.0/hosted-sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SHORTEXT_API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    purpose: "whatsapp",
    context: { agent_id: "AGI-XXXXX" },
    return_url: "https://app.example.com/settings/whatsapp",
    locale: "fr",
    expires_in: 60,
  }),
});
const { body: session } = await response.json();

// Store session.id, then redirect the user (never log the URL: it holds a secret)
res.redirect(session.url);

response = requests.post(
    "https://shortext.ny-corp.io/api/v2.0/hosted-sessions",
    headers={"Authorization": f"Bearer {os.environ['SHORTEXT_API_KEY']}", "Accept": "application/json"},
    json={
        "purpose": "whatsapp",
        "context": {"agent_id": "AGI-XXXXX"},
        "return_url": "https://app.example.com/settings/whatsapp",
        "locale": "fr",
        "expires_in": 60,
    },
)
session = response.json()["body"]

# Store session["id"], then redirect the user (never log the URL: it holds a secret)
return redirect(session["url"])

Response

{
  "success": true,
  "message": "Request success.",
  "code": 1000,
  "body": {
    "url": "https://shortext.ny-corp.io/connect/hs_...",
    "id": "9b1e4c3a-6f2d-4b8e-9a7c-2d5f8e1b0c4a",
    "purpose": "whatsapp",
    "status": "pending",
    "context": { "agent_id": "AGI-XXXXX" },
    "result": null,
    "error": null,
    "return_url": "https://app.example.com/settings/whatsapp",
    "locale": "fr",
    "expires_at": "2026-10-24T10:12:44+00:00",
    "opened_at": null,
    "finished_at": null,
    "created_at": "2026-10-24T09:12:44+00:00"
  }
}

The url contains a secret and is only returned at creation. Never log it, never share it with anyone but the user it is for.

Statuses

Status	Meaning
`pending`	Created, the page has not been opened yet.
`opened`	The user opened the page.
`completed`	Done: `result` holds what it produced.
`failed`	The step failed: `error` says why.
`cancelled`	You cancelled it with `DELETE /hosted-sessions/{id}`.
`expired`	Not finished before `expires_at`.

A session serves one outcome: once it is completed, failed, cancelled or expired, its link stops working. Create a new session to try again. The page shows how much time is left before expires_at; at zero, it reloads to its expired state.

Result

For whatsapp and mail, result lists the connected channels, in the same format as GET /channels:

{
  "channels": [
    {
      "type": "whatsapp",
      "id": "532867649916076",
      "name": "+237 6 99 99 99 99 (Acme)",
      "enabled": true,
      "agent": { "id": "AGI-XXXXX", "name": "Support" },
      "settings": null,
      "created_at": "2026-10-24T09:20:02+00:00"
    }
  ]
}

Keep the channel id: it is the channel_id you send messages from. A channel.connected webhook is also sent for each new channel. For template, result.template is the template, as returned by GET /templates/{id}. It is PENDING until Meta reviews it: follow it with the template.status_updated webhook. If Meta refuses the template, the page shows why and the session stays open, so your user can fix it and submit again.

Other endpoints

Endpoint	Use
`GET /hosted-sessions`	Your sessions, most recent first, filterable by `purpose`.
`GET /hosted-sessions/{id}`	One session, with its status and result.
`DELETE /hosted-sessions/{id}`	Cancel a session that is not finished: the link stops working.

See the guide Connect a client’s WhatsApp.

Get started

Formats

Integrations

Campaigns and follow-ups

Guides

Endpoints

Flow

Purposes

Create a session

Statuses

Result

Other endpoints

​Flow

​Purposes

​Create a session

​Statuses

​Result

​Other endpoints

Flow

Purposes

Create a session

Statuses

Result

Other endpoints