Getting Started with Jas Connect V2 API

Overview

Jas Connect is a suite of APIs designed for seamless integration with your 3CX instance. It simplifies communication with your data, offering a Data API and a Webhooks API, while also integrating the 3CX Configuration API and Call Control API for enhanced functionality.

Base URL

The base URL for all API endpoints is:

https://api.jasconnect.com/v2

What type of application is your integration?

Jas Connect currently supports two types of service principals: REGISTERED_CLIENT and JAS_APPLICATION. A REGISTERED_CLIENT is an application that integrates with a specific Jas client organization, while a JAS_APPLICATION is intended for internal Jas applications. To determine which type your application should use, please reach out to a member of the Jas team for guidance.

Authentication

Once you have identified the type of application you have, you will be provided with a client ID and secret. These credentials must be used to authenticate your application and obtain a Bearer Token, which will be required for all subsequent requests.

Basic Authentication for to obtain a bearer token

To authenticate, send a POST request to the /auth/authenticate endpoint with your credentials using Basic Authentication. Basic Authentication is created by combining your client ID and client secret provided by the Jas team into a single string, separated by a colon (:), and then encoding this string in Base64. Below are instructions and examples on how to do so.

Generating Basic Authentication Header

Combine your client ID and client secret into a single string: client_id:client_secret
Encode this string using Base64.
Prepend the encoded string with Basic.

Example in Python

import base64
import requests
 
# Your client ID and client secret
client_id = "your_client_id"
client_secret = "your_client_secret"
 
# Encode the client ID and secret in base64 for Basic Authentication
credentials = f"{client_id}:{client_secret}"
encoded_credentials = base64.b64encode(credentials.encode()).decode()
 
# Set up the Authorization header
headers = {
    "Authorization": f"Basic {encoded_credentials}"
}
 
# URL for obtaining the Bearer Token (example, adjust based on your API's token endpoint)
token_url = "https://api.jasconnect.com/v2/auth/authenticate"
 
# Make a POST request to get the Bearer Token
response = requests.post(token_url, headers=headers, data={"grant_type": "client_credentials"})
 
# Check if the request was successful
if response.status_code == 200:
    # Extract the Bearer Token from the response
    token = response.json().get("access_token")
    print(f"Bearer Token: {token}")
else:
    print(f"Failed to obtain token: {response.status_code}, {response.text}")

Example HTTP Request

POST /v2/authenticate HTTP/1.1
Host: api.jasconnect.com
Content-Type: application/json
Authorization: Basic <encoded_credentials>
 
{
  "scope": "REGISTERED_CLIENT"
}

Authorization: Basic Authentication header with encoded credentials.
scope (optional): The scope of authentication. Default is REGISTERED_CLIENT.

Response

{
    "token": "<your_jwt_token>"
}

Use this token as a Bearer token in the Authorization header for subsequent requests.

Error Handling

Common error responses include:

400 Bad Request: The request was invalid or cannot be otherwise served.
401 Unauthorized: Authentication is required and has failed or has not yet been provided.
403 Forbidden: The request was valid, but the server is refusing action.
404 Not Found: The requested resource could not be found.

For detailed error responses, refer to the respective endpoint documentation.

Jas Applications

If your application is a JAS_APPLICATION, several endpoints under /auth/* are available to manage Jas Clients and Relays. These endpoints provide functionality for managing authentication and authorization tasks related to Jas Clients, including creating, updating, and deleting client configurations, as well as managing relays for better service integration. To explore the available operations and understand how to interact with these endpoints, refer to the API documentation here. or detailed error responses, refer to the respective endpoint documentation. Furthermore, since Jas applications have access to all relays, regstrations and APIs, every request to /webhooks/*, /api/* and /xapi/* must have contain a query parameter ?relayId=<relayId> indicating which Jas organization.

Data API

Once you have obtained the Bearer Token, you can use it to make authorized requests to the Data API endpoints. To do so, include the token in the Authorization header as a Bearer token.

Here's an example of how to call an API endpoint using the Bearer token:

import requests
 
# The Bearer Token obtained previously
bearer_token = "your_bearer_token"
 
# URL of the Data API endpoint (adjust based on your API's specific endpoint)
data_api_url = "https://api.jasconnect.com/api/users"
 
# Set up the headers with the Bearer Token for authorization
headers = {
    "Authorization": f"Bearer {bearer_token}"
}
 
# Make a GET request to the Data API
response = requests.get(data_api_url, headers=headers)
 
# Check if the request was successful
if response.status_code == 200:
    # Handle the response data
    data = response.json()
    print(data)
else:
    print(f"Failed to fetch data: {response.status_code}, {response.text}")

Webhooks API

The Webhooks API in 3CX provides events for various system activities, including:

calls
recordings
voicemails
messages

By subscribing to these events, you can receive notifications whenever one of these activities occurs within your 3CX system.

Example in Python

import requests
 
# The Bearer Token obtained previously
bearer_token = "your_bearer_token"
 
# URL of the Webhooks API endpoint for registering events
webhook_api_url = "https://api.jasconnect.com/v2/webhooks"
 
# Events to subscribe to
events = ["new_recording", "new_voicemail", "new_message", "call_status"]
 
for event in events:
    data = {
        "event": event,
        "url": f"https://your-callback-url.com/{event}"
    }
 
    headers = {
        "Authorization": f"Bearer {bearer_token}",
        "Content-Type": "application/json"
    }
 
    response = requests.post(webhook_api_url, json=data, headers=headers)
 
    if response.status_code == 200:
        print("Successfully registered for events")
    else:
        print(f"Failed to register for events: {response.status_code}, {response.text}")

Webhook Event Payloads

Below are examples of webhook payloads for supported events:

📼 `new_recording`

Triggered on call end, this event provides details about the newly available call recording.

Example Payload:

{
  "timestamp": "2025-04-10T11:53:24.157990991-04:00",
  "data": {
    "start_time": "2025-04-10T15:53:16.105033Z",
    "end_time": "2025-04-10T15:53:24.03135Z",
    "recording_url": "101/[Amimer, Nabil]_101-5148335350_20250410155316(20).wav",
    "transcription": "",
    "archived_url": "",
    "id_recording": 145,
    "cl_participants_id": 0,
    "call_type": 2,
    "archived": false
  },
  "eventName": "new_recording"
}

Fields:

Field	Type	Description
`start_time`	`string`	UTC timestamp when the call began
`end_time`	`string`	UTC timestamp when the call ended
`recording_url`	`string`	URL path to the call recording
`transcription`	`string`	(Optional) Transcribed text of the call
`archived_url`	`string`	(Optional) URL to the archived recording
`id_recording`	`integer`	Unique identifier for the recording
`call_type`	`integer`	Type of call (e.g., 1: incoming, 2: outgoing)
`archived`	`boolean`	Indicates whether the recording is archived

💬 `new_message`

Triggered when a new chat message is sent.

Example Payload:

{
  "timestamp": "2025-04-10T11:58:25.976507922-04:00",
  "data": {
    "time_sent": "2025-04-10T15:58:25.967555Z",
    "edited_at": "0001-01-01T00:00:00Z",
    "msg_gid": "73a13e47d10342bc9a850097a429a037",
    "message": "hello",
    "public_file_name": "",
    "internal_file_name": "",
    "party": "",
    "group_no": "",
    "replyon_msg_gid": "",
    "file_info": "",
    "param": "",
    "fkid_chat_conversation": 1,
    "replyon_id": 0,
    "id_message": 51,
    "message_type": 0,
    "forward_id": 0
  },
  "eventName": "new_message"
}

Fields:

Field	Type	Description
`time_sent`	`string`	UTC timestamp when the message was sent
`edited_at`	`string`	Timestamp of last edit (or default value if never edited)
`msg_gid`	`string`	Unique global ID for the message
`message`	`string`	Message text
`public_file_name`	`string`	Name of file (if any) attached for public access
`internal_file_name`	`string`	Internal reference to the uploaded file
`fkid_chat_conversation`	`integer`	Chat conversation ID
`id_message`	`integer`	Internal message ID
`message_type`	`integer`	Type of message (e.g., 0: text, 1: file)

⚠️ Additional webhook types such as new_voicemail and call_status follow similar structures and will be documented in future updates.

📞 Call Status Events

The call_status event tracks the real-time state of participants in active calls. Each event is tied to a specific participant and includes a reference to their entity, which can be queried for more details.

📄 Event Structure

{
  "timestamp": "2025-04-10T12:55:35.930348169-04:00",
  "data": {
    "event": {
      "attached_data": null,
      "entity": "/callcontrol/{callId}/participants/{participantId}",
      "event_type": 0 | 1
    },
    "sequence": 102
  },
  "eventName": "call_status"
}

🔍 Accessing Detailed Call Data

You can use the entity field to fetch full details about the participant's call status by making a request to:

GET {baseUrl}/api/callcontrol/{dn}/participants/{id}

This returns information such as:

status: Ringing, Connected, On Hold, etc.
dn: Extension or direct number of the participant
party_caller_name, party_caller_id, party_dn: Caller identification
device_id: The SIP device in use
callid, legid: Identifiers for the call session and participant leg

📌 Example Participant Data

{
  "id": 57,
  "status": "Connected",
  "dn": "10000",
  "party_caller_name": "Amimer, Nabil",
  "party_dn": "101",
  "party_caller_id": "5148335350",
  "device_id": "sip:10000@3cx.reg.skyetel.com",
  "callid": 28,
  "legid": 2
}

This represents a participant (10000) connected to external number 5148335350 in call session 28.

Webhook Authentication

To ensure secure delivery of webhook events, Jas Connect will soon introduce signature verification to validate payload authenticity. This involves computing an HMAC hash of the payload using a shared secret and comparing it against the signature header.

Documentation for webhook authentication is coming soon.

3CX Configuration and Call Control API

3CX Version 20 introduced the Call Control API and the Configuration API (xapi). Jas Connect offers these endpoints accessible without additional authentication. However, proper permissions must be configured in the 3CX admin portal to ensure secure access. Administrators can manage these permissions in the API section of the portal, allowing control over who can access and interact with the API while maintaining system security.

See the endpoints Call Control API and Configuration API

Contact

For any questions or issues, please contact:

Email: info@jascommunications.ca

Introduction Jas Connect API

Getting Started with Jas Connect V2 API

Overview

Base URL

What type of application is your integration?

Authentication

Basic Authentication for to obtain a bearer token

Generating Basic Authentication Header

Example in Python

Example HTTP Request

Response

Error Handling

Jas Applications

Data API

Webhooks API

Example in Python

Webhook Event Payloads

📼 new_recording

💬 new_message

📞 Call Status Events

📄 Event Structure

🔍 Accessing Detailed Call Data

📌 Example Participant Data

Webhook Authentication

3CX Configuration and Call Control API

Contact

📼 `new_recording`

💬 `new_message`