Skip to content
Thirdlane

Actions

Actions are imperative endpoints that make something happen right now: place a call, send a message, or control a live call. They are the building blocks for click-to-call, notifications, agent tooling, and AI-driven interactions.

All examples use https://your-server.thirdlane.com and tenant acme; authenticate with an X-API-Key header (see API Basics).

Place a call

Placing a call uses a callback model: the platform first rings the originator’s own mobile, then dials the destination and bridges the two legs.

Terminal window
curl -X POST https://your-server.thirdlane.com/api/telephony/call \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"2025551000","to":"2025559876"}'

from must match the calling user’s configured mobile number.

Send a message

Send an SMS or WhatsApp message through a configured messaging channel. For template-only channels, pass a template_id (and optionally a contact_id or explicit variables to fill template placeholders).

Terminal window
curl -X POST https://your-server.thirdlane.com/api/messaging/send \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_id":3,"to":"+12025559876","body":"Your order has shipped."}'

See Messaging Channels to set up channels and Message Templates for templates.

Send a Connect message

Post a message into a Thirdlane Connect channel - for example, to notify a team that a customer is waiting, or to hand off context when transferring a call to a queue. Provide the channel name; the server resolves it within the caller’s tenant, so a tenant-scoped key cannot post into another tenant’s channel.

Terminal window
curl -X POST https://your-server.thirdlane.com/api/connect/message/acme \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"sales","body":"Customer on hold, line 2","from_name":"Support Bot"}'

The response returns the resolved channel JID:

{ "status": "sent", "to": "sales", "target": "channel", "jid": "sales@muc.acme.local" }

Set body_type to JSON to send a structured payload (the body must then be a valid JSON string).

Send a Connect direct message

Send a 1:1 direct message from one Connect user to another - for example, an AI-agent user handing off context to a live agent when transferring a call. Set target to user, to to the recipient’s extension, and from_ext to the sender’s extension. Offline recipients receive the message via offline storage and message archive.

Terminal window
curl -X POST https://your-server.thirdlane.com/api/connect/message/acme \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"user","to":"1002","from_ext":"1900","body":"Transferring Jane Doe - she is asking about invoice 4471."}'
{ "status": "sent", "to": "1002", "target": "user", "jid": "acme-1002@acme.local", "from": "acme-1900@acme.local" }

Provision a Connect agent user

Create a Connect-enabled extension for an AI agent and get back everything it needs to sign in: the Connect web + XMPP username/password, a SIP auth id/secret for calling, and the per-plane server URLs. Only extension is required; passwords are generated when omitted.

The password is returned only in this response (it is stored hashed and cannot be read back later), so capture it at provisioning time. To change it later, use the rotate endpoint below.

Terminal window
curl -X POST https://your-server.thirdlane.com/api/connect/agent/acme \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"extension":"1900","first_name":"Support","last_name":"Bot"}'
{
  "status": "provisioned",
  "tenant": "acme",
  "extension": "1900",
  "connect": {
    "username": "acme-1900",
    "password": "Xy7pQ2mK9wLz",
    "jid": "acme-1900@acme.local",
    "websocket_url": "wss://your-server.thirdlane.com/xmpp-websocket",
    "login_url": "https://your-server.thirdlane.com/"
  },
  "sip": {
    "extension": "1900",
    "auth_id": "1900-acme",
    "password": "k3Jd8sHf2LqPzR4x",
    "domain": "your-server.thirdlane.com",
    "websocket_url": "wss://your-server.thirdlane.com/wss"
  },
  "endpoints": {
    "management": "https://your-server.thirdlane.com/api",
    "messaging": "https://your-server.thirdlane.com/api/messaging",
    "reporting": "https://your-server.thirdlane.com/api/reports",
    "media": "https://your-server.thirdlane.com",
    "connect_ws": "wss://your-server.thirdlane.com/xmpp-websocket"
  }
}

The Connect username/password work for both the Connect web login (login_url) and the XMPP messaging session (websocket_url). The SIP block is for placing and receiving calls.

Rotate an agent password

Rotate the Connect (web + XMPP) password for an existing agent user. Returns the same bundle with the new password; the SIP secret is left unchanged.

Terminal window
curl -X POST https://your-server.thirdlane.com/api/connect/agent/acme/1900/rotate \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Control a live call

These endpoints act on a live Asterisk channel. You typically obtain the channel from a call event or an active-calls source. On multi-tenant systems a tenant-scoped key may only control channels that belong to its own tenant.

Hang up

Terminal window
curl -X POST https://your-server.thirdlane.com/api/telephony/hangup \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"SIP/102-acme-00000043"}'

Transfer (blind)

Redirects the given channel to another extension or number.

Terminal window
curl -X POST https://your-server.thirdlane.com/api/telephony/transfer \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"SIP/102-acme-00000043","to":"2001"}'

Record (start / stop)

Starts or stops recording on a channel. The action field is start (default) or stop; filename is optional.

Terminal window
curl -X POST https://your-server.thirdlane.com/api/telephony/record \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"SIP/102-acme-00000043","action":"start"}'

Ad-hoc recordings started this way are written to the recording directory but are not automatically indexed into the recordings database. To retrieve recordings that are indexed (for example, calls recorded by policy), use Reporting.

Hold and unhold are planned as a follow-on.