Your software controls the calls. The softphone reports back.

1. Enable “Let other programs on this computer drive the phone”

   The server starts immediately. It listens on the loopback interface only, so it is reachable from this computer and not from the office network, a VPN or other machines.

2. Choose a port

   The default is 8377. Change it only if another application already uses that port.

3. Set a token (optional)

   Without a token, any program on this computer can read data and control calls. When a token is set, it is also required for all requests that change stored data.

4. Select access groups

   Contacts, call history, calls and call control, accounts, settings, metrics. Disabling a group is not a response filter: its endpoints are not served at all.

5. Test the connection

   curl http://127.0.0.1:8377/accounts. If the response is JSON, the API is working and the rest of this page is reference material.

Access levels

Access control is based on changing stored data, not on reading. Without a token, clients can read everything covered by the enabled groups and control active calls: place, answer, hang up, hold, resume, transfer and send DTMF. With the token in the Authorization header, clients can also use write endpoints; without it, those endpoints are neither served nor listed on the index page.

# read requests need no token
curl http://127.0.0.1:8377/accounts

# write requests need the token from Settings
curl -X POST http://127.0.0.1:8377/calls \
  -H 'Authorization: <your token>' \
  -H 'Content-Type: application/json' \
  -d '{"number":"+15551234567","account_id":"aa24a2c4-709b-402a-ac58-7ca6788dcb94"}'

Make sure whoever approves the integration understands this: without a token, any program running on this computer can control the softphone, including answering calls. On a single-user workstation this is usually acceptable. On shared or managed machines, set a token and handle it like any other credential.

Access groups

Six groups: contacts, call history, calls and call control, accounts, settings, metrics. When a group is disabled, its paths return 404 {"error":"no such endpoint"}, exactly like a non-existent path, and the refusal is counted in api_requests_refused_total.

Events

Each event can be enabled separately. A screen-pop integration may subscribe to the first event only; a call-logging integration may subscribe to the last one only. Disabled events are listed in settings.webhooks.silenced, so support tools can see which events a workstation sends.

Request format

One HTTP request per event is sent to the configured URL, with a JSON body and your custom header, if set. The call’s id is the same UUID as in GET /calls and /calls/{id}/…, so both mechanisms work together: an event signals a change, and the REST API returns the current details.

Use “Send a test event” before writing the parser. It sends a sample event for a fictitious call directly to your endpoint, with the same headers as a real event. Log the raw request body and build your receiver against what your version actually sends.

{
        "event":        "call-started",                           // call-started, call-state-changed or call-ended
        "id":           "7620f1c5-fa8e-4453-80bf-4274f5324bec",   // same id as in /calls
        "direction":    "in",
        "state":        "ringing-in",                             // same values as state in /calls
        "number":       "+15551234567",                           // match CRM records on this field
        "name":         "Jane Miller",                            // resolved from contacts, may be ""
        "uri":          "sip:+15551234567@pbx.example.com",
        "dialed":       "",
        "account":      "1001@pbx.example.com",                   // line used for the call
        "account_id":   "aa24a2c4-709b-402a-ac58-7ca6788dcb94",
        "event_ts":     "1788788890412",                          // Unix milliseconds, as a string
        "duration_s":   "0",
        "reason":       "none",
        "answered_by":  "no",
        "seance_id":    "0b6f1d2e-5c3a-4f8e-9a71-2d4c6e8f0a13",   // shared across transfers and conferences
        "callstart_ts": "1788788890398",
        "callstate_ts": "1788788890398"
      }

Event fields

In webhooks every value is a string, numbers and instants included: "duration_s": "42", "event_ts": "1788788942412". An unknown instant is an empty string. In the REST API the same fields are JSON numbers, and an unknown instant is null.

One conversation across transfers

seance_id groups the calls that make up one conversation. A call placed or received from scratch starts a new seance. A call created by a transfer, a call that replaces another, a consultation about a call and every call joined into a conference keep the seance of the call they came from. Between phones the seance travels in the SIP header X-Seance-Id: when a call is transferred to a colleague who also uses AI Softphone and the PBX passes the header through, both workstations report the same seance_id.

Receiver example

About thirty lines with no dependencies beyond a web framework. It returns 200 immediately and processes the event afterwards — the key rule for webhook receivers.

from flask import Flask, request
      import threading, logging
      
      app = Flask(__name__)
      SECRET = "the value you pasted into Settings"
      
      # Respond immediately; process the event outside the request thread.
      # A slow receiver does not slow down the softphone, but it fills
      # the delivery queue, and a full queue drops events.
      def handle(event):
          if event.get("event") != "call-started":  # a screen pop needs the first event only
              return
          number = event.get("number") or ""
          customer = crm.find_by_phone(number)          # your code
          if customer:
              crm.pop_card(customer.id)                 # your code
          else:
              crm.pop_new_lead(number)                  # your code
      
      @app.route("/webhooks", methods=["POST", "GET"])
      def webhooks():
          if request.headers.get("Authorization") != SECRET:
              return "", 401
      
          event = request.get_json(silent=True) or request.args.to_dict()
          logging.info("softphone event: %s", event)   # keep for a week
      
          threading.Thread(target=handle, args=(event,), daemon=True).start()
          return "", 200
      
      if __name__ == "__main__":
          app.run(host="0.0.0.0", port=8080)

const express = require("express");
      const app = express();
      app.use(express.json());
      
      const SECRET = process.env.SOFTPHONE_SECRET;
      
      app.all("/webhooks", (req, res) => {
        if (req.get("Authorization") !== SECRET) return res.sendStatus(401);
      
        const event = Object.keys(req.body || {}).length ? req.body : req.query;
        res.sendStatus(200);                     // respond first
      
        setImmediate(() => handle(event));       // then process
      });
      
      app.listen(8080);

Delivery semantics

Events are queued instead of being sent from the call-handling thread, so a slow receiver never delays ringing or transfers. If the queue fills up, events are dropped and counted in webhooks_dropped_total. Rejected and failed deliveries are counted as well. Events are delivered in order and at least once: make your handler idempotent, keyed on id, event and callstate_ts.

With GET, a URL template can be used instead of a plain URL: each [field] is replaced with that field’s value, percent-encoded — for example https://crm.local/pop?phone=[number]&call=[id]. Placeholders use the field names listed above. Templates saved with the earlier names ([accountId], [at], [duration], [answeredBy], [seanceId]) keep working.

Webhooks are sent from the workstation, so the URL only has to be reachable from that computer. An internal http://crm.local/calls works as well as a public HTTPS endpoint, and no inbound firewall rules are required.

The one setting that requires a deliberate decision: without a token, any program running on that computer can read the contacts and call history allowed by the access groups and control calls. This is acceptable on a personal workstation, but not on shared or kiosk machines. There, set a token, keep it out of source control and give it only to the integration that needs it.

Recordings and transcripts are not available as JSON. The API serves them as HTML pages: /ui, and /ui/recordings/{id} for a recording with its transcript. Link to these pages from your CRM instead of transferring audio: the link opens on the workstation that stores the recording, and the audio never leaves it.