User Tools

Site Tools


api:pbx:events:test

API : PBX : Events Test

Introduction

A PBX event is a rule that runs actions - a webhook, an SMS, a call, setting a variable or a switch, or changing the members of a queue - when something happens on the PBX. See PBX events for the triggers, the variables and the limits.

This request runs the actions of an event now, without waiting for its trigger, with variables of your own choosing. Use it to check a webhook, an SMS text or a call before the event goes live.

A test is for real: the webhook is called, the SMS is sent and billed, the call is placed, the variable and switch are set, and the members of the queue are changed. Test runs count towards the limits.

  • A disabled event (enabled false) can be tested too.
  • The variables of every run are filled in by themselves: EVENT_TYPE is TEST, and TIME, TIMESTAMP, GUID and EVENT_ID as usual. Variables you send are added on top and win - so you can e.g. send EVENT_TYPE CALL_END to test a webhook that looks at it.
  • A variable the event uses, but you do not send, is empty - except %VARIABLE:name% and %SWITCH:name%, which are looked up as usual unless you send them, e.g. SWITCH:door1: 1.
  • A queue action with TRIGGER takes the queue from the QUEUE_ID you send, and the extension from MEMBER_EXTENSION_ID, or else EXTENSION_ID. If you do not send them, the action fails with no_trigger_queue or no_trigger_extension.
  • The test run is written to the run log with test true and summary TEST. A test that cannot run at all - e.g. because the event was deleted in the meantime - is logged with type null, no actions and a summary that starts with TEST failed: and gives the reason.
  • An event can only be tested once at a time: while a test of it is waiting for its run (at most 10 seconds), another test of the same event is refused with 429.

The request waits up to 15 seconds for the run to finish and then answers with the run. If the run takes longer, the request answers 202 with a requestId, and the run shows up in the log with that requestId when it is done. If it never shows up, the test did not reach the service that runs the events - try again later.

Request

URL https://api.telecomx.dk/pbx/events/EVENT_ID/test
Method POST
Access level MANAGER or OWNER if user belongs to the customer.
RESELLER if customer belongs to the reseller.
ADMIN.
Param EVENT_ID Id Id of the event to test (24 hex-char string).
Body variables Object [optional] The variables to run the actions with, as name: value. At most 50. Each name is upper case letters and underscores, optionally followed by : and the name of a PBX variable or switch (e.g. A_NUMBER or SWITCH:door1), at most 64 characters. Each value is a string of at most 1024 characters.

The body may be left out altogether.

Request body example

{
  variables: {
    EVENT_TYPE: 'CALL_END',
    A_NUMBER: '+4512345678',
    A_NAME: 'Anna Hansen',
    B_NUMBER: '+4570123456',
    CONVERSATION_DURATION: '131'
  }
}

Response

200 when the run finished within 15 seconds:

JSON object
log Object The run, as described in Log.

202 when it did not:

JSON object
requestId String Id of the test request. The run has this requestId in the log.
pending Boolean Always true.

Example - 200

{
  log: {
    _id: '6728a1b2c3d4e5f601234568',
    customer: '1234567890123456789ABCDE',
    event: '12345678901234567890ABCD',
    type: 'CALL_END',
    summary: 'TEST',
    test: true,
    requestId: '3f2a9c1e-5b7d-4e8f-a0b1-c2d3e4f5a6b7',
    variables: {
      EVENT_TYPE: 'CALL_END',
      TIME: '2026-11-04 14:31:10',
      TIMESTAMP: '1793799070',
      GUID: '9a0e3d2f-1c4b-4a69-b6f0-c3a26c1e4f57',
      EVENT_ID: '12345678901234567890ABCD',
      A_NUMBER: '+4512345678',
      A_NAME: 'Anna Hansen',
      B_NUMBER: '+4570123456',
      CONVERSATION_DURATION: '131'
    },
    actions: [
      { action: 'WEBHOOK', success: true, status: 200, error: null, ms: 92 },
      { action: 'SMS', success: true, status: null, error: null, ms: 340 }
    ],
    createdAt: '2026-11-04T13:31:10.000Z'
  }
}

Example - 202

{
  requestId: '3f2a9c1e-5b7d-4e8f-a0b1-c2d3e4f5a6b7',
  pending: true
}

Errors

Error code Message Description
403 access_denied Insufficient access level
404 id Event not found
422 id Invalid ObjectId
422 variables At most 50 variables
422 variables.name Invalid key in record - the variable name is not valid
422 variables.name The value is not a string, or longer than 1024 characters
429 test A test of this event is already running
500 internal_error <Unspecified>
api/pbx/events/test.txt · Last modified: by Telecom X AI

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki