Connect a client's WhatsApp

This guide walks through the hosted session flow for the whatsapp purpose. Your key needs Manage integrations.

1. Prepare the agent

Create or choose the agent that will answer on the client’s number (POST /agents or GET /agents). Keep its id, AGI-XXXXX.

2. Create the session when the client clicks “Connect WhatsApp”

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"])

Store body.id with the client it belongs to, then redirect the client to body.url. The link is valid for expires_in minutes (60 by default, 24 hours at most).

3. The client connects their number

On the Shortext page, the client logs in to Facebook, chooses or creates their Meta business portfolio and WhatsApp Business account, then adds and verifies their number. Shortext then sends them to:

https://app.example.com/settings/whatsapp?session_id=9b1e4c3a-...&status=completed

4. Confirm on your server

Show a waiting state on your return page, and confirm with your server:

listen to hosted_session.completed / hosted_session.failed on your webhook (filter on purpose if needed), or
call GET /hosted-sessions/{session_id}.

On success, result.channels lists the connected numbers:

{
  "id": "9b1e4c3a-6f2d-4b8e-9a7c-2d5f8e1b0c4a",
  "purpose": "whatsapp",
  "status": "completed",
  "result": {
    "channels": [
      { "type": "whatsapp", "id": "532867649916076", "name": "+237 6 99 99 99 99 (Acme)", "enabled": true, "agent": { "id": "AGI-XXXXX", "name": "Support" } }
    ]
  },
  "error": null
}

Save each channel id for the client: it is the channel_id to send messages from. On failed, show error and offer to try again with a new session.

5. Go further

Send the client’s first messages with templates.
Move the number to another agent with PUT /channels/whatsapp/{id}/agent.
Connect a mailbox the same way with the mail purpose.

Get started

Formats

Integrations

Guides

Endpoints

Connect a client's WhatsApp

1. Prepare the agent

2. Create the session when the client clicks “Connect WhatsApp”

3. The client connects their number

4. Confirm on your server

5. Go further

​1. Prepare the agent

​2. Create the session when the client clicks “Connect WhatsApp”

​3. The client connects their number

​4. Confirm on your server

​5. Go further

1. Prepare the agent

2. Create the session when the client clicks “Connect WhatsApp”

3. The client connects their number

4. Confirm on your server

5. Go further