Wesal Cloud API Documentation

API Documentation for Our Platforms

WesalVoC API

Voice of Customer (VoC) platform for collecting and analyzing customer feedback through surveys.

Introduction

Welcome to the Wesal Cloud API documentation. This API provides endpoints for managing authentication and accessing survey data in the WesalVoC platform.

Base URL

https://api.wesal.cloud/api/v1

API Version

Current version: v1

Authentication

The API uses token-based authentication. After logging in, you'll receive a JWT token that must be included in subsequent requests.

Using the Token

Include the token in the Authorization header:

Authorization: YOUR_TOKEN_HERE
Note: Some endpoints require the X-Client-Id header with a Base64 encoded value.

1. Login

POST /auth/login

Authenticate a user and receive an access token for subsequent API calls. Two authentication modes are supported: User Account and API Token.

Headers

Header Value Required Description
Content-Type application/json Yes Request content type
X-Client-Id RW5jb2RlIHRvIEJhc2U2NCBmb3JtYXQ Yes Base64 encoded client identifier

Request Body - Common Fields

Field Type Required Description
company string Yes Company identifier

Authentication Mode 1: User Account

Use this mode to authenticate with user email and password credentials.

Additional Fields

Field Type Required Description
email string Yes User email address
password string Yes User password

Example Request - User Account

{
    "company": "COMPANY_NAME",
    "email": "user@example.com",
    "password": "USER_PASSWORD"
}

Authentication Mode 2: API Token

Use this mode to authenticate with API token for enhanced security and control. This is the recommended method for API integrations.

Additional Fields

Field Type Required Description
email string Yes User email address
password string Yes API token (use instead of user password)

Example Request - API Token

{
    "company": "COMPANY_NAME",
    "email": "user@example.com",
    "password": "YOUR_API_TOKEN_HERE"
}
Note: For production environments and automated integrations, always use API Token authentication mode. API tokens provide better security, can be easily revoked, and allow for granular access control without exposing actual user passwords.

Response

200 OK

Response Body

Field Type Description
user object User information including profile and company details
token string JWT authentication token
result string Operation result status

Example Response

{
    "user": {
        "_id": "37e4be421508c0e91f59d752",
        "uuid": "1d285d8a-aaee-4e27-a3ef-3bd26d6cc3b0",
        "firstName": "First Name",
        "lastName": "Last Name",
        "email": "user@example.com",
        "phone": "0500000000",
        "role": "admin",
        "status": "active",
        "createdAt": "2025-01-08T10:50:19.128Z",
        "updatedAt": "2025-03-16T11:19:23.625Z",
        "company": {
            "_id": "37e4be421508c0e91f59d752",
            "name": "COMPANY_NAME",
            "settings": {
                "region": "mypurecloud.de",
                "questionsSchema": [
                    {
                        "id": "AgentSatisfaction",
                        "name": "Agent Satisfaction",
                        "type": "rating",
                        "minAnswer": 1,
                        "maxAnswer": 5,
                        "counts": 5
                    },
                    {
                        "id": "ServiceSatisfaction",
                        "name": "Service Satisfaction",
                        "type": "rating",
                        "minAnswer": 1,
                        "maxAnswer": 5,
                        "counts": 5
                    }
                ]
            }
        }        
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "result": "success"
}

2. Get Surveys

POST /apps/wesalvoc/queries/surveys

Retrieve survey data based on specified filters including date range, agents, queues, and answers.

Headers

Header Value Required Description
Content-Type application/json Yes Request content type
Authorization {{token}} Yes JWT token from login response

Request Body

Field Type Required Description
startDate string Yes Start date in ISO 8601 format
endDate string Yes End date in ISO 8601 format
agents array Yes Array of agent names to filter by
queues array Yes Array of queue names to filter by
wrapup string No Wrap-up category
answers object Yes Filter criteria for survey answers
companyId string Yes Company identifier
page number Yes Page number for pagination

Example Request

{
    "startDate": "2025-11-01T00:00:00",
    "endDate": "2025-11-12T23:59:59",
    "agents": [],
    "queues": ["Sales"],
    "wrapup": ["Inquiries"],
    "answers": {
        "ServiceSatisfaction": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"],
        "AgentSatisfaction": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"],
        "interactionType": ["voice"]
    },
    "companyId": "37e4be421508c0e91f....",
    "page": 1
}

Response

200 OK

Response Body

Field Type Description
surveys array Array of survey objects
total number Total number of surveys matching criteria
pageTotal number Number of surveys in current page
result string Operation result status

Survey Object Structure

Field Type Description
_id string Unique survey identifier
interactionId string Associated interaction ID
surveyDate string Survey completion date
type string Interaction type (e.g., voice)
number string Contact number
direction string Call direction (inbound/outbound)
queue string Queue name
agent string Agent name
answers object Survey answers object

Example Response

{
    "surveys": [
        {
            "_id": "6912d1249dfba0a82101ce9f",
            "interactionId": "a08013f9-5458-4f14-a4c8-fc41b451dbe4",
            "surveyDate": "2025-11-11T08:58:37",
            "type": "voice",
            "number": "tel:+966×××××××××",
            "direction": "inbound",
            "queue": "Sales",
            "agent": "Nourah",
            "wrapup": "Inquiries",
            "answers": {
                "ServiceSatisfaction": "4",
                "AgentSatisfaction": "5"
            }
        },
        {
            "_id": "6912d13f9dfba0a82101cea0",
            "interactionId": "a08013f9-5458-4f14-a4c8-fc41b451dbe2",
            "surveyDate": "2025-11-11T08:58:37",
            "type": "voice",
            "number": "tel:+966×××××××××",
            "direction": "inbound",
            "queue": "Sales",
            "agent": "Ahmed",
            "wrapup": "Inquiries",
            "answers": {
                "ServiceSatisfaction": "3",
                "AgentSatisfaction": "4"
            }
        }
    ],
    "total": 2,
    "pageTotal": 2,
    "result": "success"
}

3. Create Survey

POST /apps/wesalvoc/surveys

Submit a new survey response. If a survey with the same interactionId already exists, its answers will be updated. Supports two sender types: public and data_action.

Rate Limit: 1 request per 10 seconds per interactionId. A duplicate call within 10 seconds returns 429 Too Many Requests — but if the interaction already exists in the database it will still update on a second call after the window.

Headers

Header Value Required Description
Content-Type application/json Yes Request content type
Authorization YOUR_TOKEN_HERE Yes JWT token provided by Wesal
X-Client-Id YOUR_CLIENT_ID Yes Client identifier provided by admin

Request Body — sender: public

Use this sender when submitting from a web/app integration where surveyData is a JSON object.

Field Type Required Description
sender string Yes Must be "public"
surveyData.companyId string Yes Company MongoDB ObjectId
surveyData.interactionId string Yes Unique interaction identifier (UUID)
surveyData.direction string No Call direction e.g. Inbound / Outbound. Defaults to empty string.
surveyData.surveyDate string No Survey date (overridden by server timestamp)
surveyData.type string Yes Interaction type e.g. Voice
surveyData.number string Yes Customer phone number
surveyData.wrapup string No Wrap-up category
surveyData.queue string Yes Queue name
surveyData.agent string Yes Agent name
surveyData.answers object Yes Key-value pairs of question ID to answer value

Example Request

{
    "sender": "public",
    "surveyData": {
        "companyId": "67e4be421508c0e91....",
        "direction": "Inbound",
        "interactionId": "88888888-8888-8888-8888-888888888888",
        "surveyDate": "2023-01-28T12:02:54",
        "type": "Voice",
        "number": "0500000000",
        "queue": "Sales",
        "agent": "Mohammed",
        "wrapup": "Inquiries",
        "answers": {
            "ServiceSatisfaction": "1",
            "AgentSatisfaction": "2"
        }
    }
}

Request Body — sender: data_action

Use this sender when submitting from Genesys Data Actions where surveyData is a JSON-encoded string.

Field Type Required Description
sender string Yes Must be "data_action"
surveyData string Yes JSON-encoded string containing the same fields as the public sender's surveyData object

Example Request

{
    "sender": "data_action",
    "surveyData": "{\"companyId\":\"6a2e6d6d59d417bb...\",\"wrapup\":\"inquiries\",\"interactionId\":\"88888888-8888-8888-8888-888888888888\",\"surveyDate\":\"2023-01-28T12:02:54\",\"type\":\"Voice\",\"number\":\"0500000000\",\"queue\":\"Sales\",\"agent\":\"Mohammed\",\"answers\":{\"ServiceSatisfaction\":\"2\"}}"
}

Response

201 Created — new survey 200 OK — existing survey updated

Example Response — Created

{
    "result": "success",
    "message": "Survey created",
    "data": {
        "_id": "68598f1e3b2a4c001....",
        "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "interactionId": "88888888-8888-8888-8888-888888888888",
        "surveyDate": "2026-06-25T10:30:00",
        "direction": "Inbound",
        "type": "Voice",
        "number": "0500000000",
        "queue": "Sales",
        "agent": "Mohammed",
        "wrapup": "Inquiries",
        "answers": {
            "ServiceSatisfaction": "1",
            "AgentSatisfaction": "2"
        }
    }
}

Example Response — Updated

{
    "result": "success",
    "message": "Survey updated",
    "data": { ... }
}

Error Responses

Status Message Reason
400 Missing sender or surveyData Required fields not provided
400 Invalid sender sender is not public or data_action
401 Authorization header is required Missing Authorization header
401 X-Client-Id header is required Missing X-Client-Id header
403 Forbidden: Invalid client ID X-Client-Id not in allowed list
404 Company not found companyId does not match any company
429 Too many requests, please wait 10 seconds before retrying. Rate limit exceeded for this interactionId

4. Reset Password

POST /auth/reset

Initiate a password reset process. A verification code will be sent to the user's email or phone.

Headers

Header Value Required Description
Content-Type application/json Yes Request content type

Request Body

Field Type Required Description
companyId string Yes Company identifier
method string Yes Reset method: "email" or "phone"
email string Conditional User email address (required if method is "email")
phone string Conditional User phone number (required if method is "phone")
Note: Pass phone value as "NO" if method is email and vice versa.

Example Request

{
    "companyId": "37e4be421508c0e91f....",
    "method": "email",
    "email": "user@example.com",
    "phone": "NO"
}

Response

200 OK

Example Response

{
    "result": "success",
    "message": "Reset done, please check your email"
}

5. Reset Password - Verify

POST /auth/verify

Complete the password reset process by verifying the code and setting a new password.

Headers

Header Value Required Description
Content-Type application/json Yes Request content type

Request Body

Field Type Required Description
companyId string Yes Company identifier
method string Yes Reset method: "email" or "phone"
email string Yes User email address
verifyCode string No Verification code from email
otp string Yes One-time password/verification code
password string Yes New password

Example Request

{
    "companyId": "37e4be421508c0e91f....",
    "method": "email",
    "email": "user@example.com",
    "verifyCode": "",
    "otp": "1234",
    "password": "NEW_PASSWORD"
}

Response

Success Response

200 OK 
{
    "result": "success",
    "message": "Password reset successfully"
}

Error Response

404 Not Found 
{
    "result": "error",
    "message": "Incorrect verify code"
}

6. Logout

GET /auth/logout

Logout the current user and invalidate the authentication token.

Headers

Header Value Required Description
Content-Type application/json Yes Request content type
Authorization {{token}} Yes JWT token from login response

Response

200 OK 
{
    "result": "success",
    "message": "Logged out successfully"
}

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of requests.

Status Code Description
200 OK - Request successful
400 Bad Request - Invalid request parameters
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Resource not found
500 Internal Server Error - Server-side error

WesalPulse API

WesalPulse reporting endpoints (Dashboard + Genesys reports).

Introduction

Welcome to the WesalPulse API v1 documentation. This API provides endpoints for OAuth authentication and reporting.

Base URL

https://api.wesalpulse.com/api/v1
Note: All endpoints below are shown relative to /api/v1.

Authentication

WesalPulse uses OAuth 2.0 client_credentials to issue a Bearer access token (JWT). Use that token in the Authorization header for secured endpoints.

Using the Token

Authorization: Bearer <access_token>

1. OAuth - Create Access Token

POST /oauth/token

Issue an access token using the OAuth client credentials flow.

Headers

Header Value Required Description
Authorization Basic base64(client_id:client_secret) Yes OAuth client credentials
Content-Type application/x-www-form-urlencoded Yes Form-encoded request body
Accept application/json No Response type

Request Body

Field Type Required Description
grant_type string Yes Must be client_credentials

Example Request

grant_type=client_credentials

Response

200 OK

Example Response

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 86400
}

2. Me

GET /auth/me

Return the authenticated principal context.

Headers

Header Value Required Description
Authorization Bearer <access_token> Yes JWT access token
Accept application/json No Response type

Response

200 OK

Example Response

{
  "user": {
    "organizationId": "...",
    "permissions": ["..."]
  }
}

3. Dashboard Summary

GET /reports/dashboard

Return a dashboard summary for the selected date range.

Headers

Header Value Required Description
Authorization Bearer <access_token> Yes JWT access token
Accept application/json No Response type

Query Parameters

Parameter Type Required Description
dateRange string No Date range preset (e.g. today, this_week, custom)
startDate string No Required when dateRange=custom (ISO-8601)
endDate string No Required when dateRange=custom (ISO-8601)

4. Queues Activity

GET /reports/genesys/queues/activity

Return Genesys queue activity for today (00:00 - now).

Note: This endpoint always returns data for today; startDate/endDate are ignored in the backend.

Query Parameters

Parameter Type Required Description
mediaTypes string No Comma-separated list (e.g. voice,chat)

5. Queues Performance

GET /reports/genesys/queues/performance

Return Genesys queues performance metrics for a time range.

Query Parameters

Parameter Type Required Description
startDate string Yes ISO-8601
endDate string Yes ISO-8601
mediaTypes string No Comma-separated list (e.g. voice,chat)
directions string No Comma-separated list (e.g. inbound,outbound)
debug string No true/false

6. Queues Routing

GET /reports/genesys/queues/routing

Return Genesys queues routing metrics for a time range.

Query Parameters

Parameter Type Required Description
startDate string Yes ISO-8601
endDate string Yes ISO-8601
mediaTypes string No Comma-separated list (e.g. voice,chat)
directions string No Comma-separated list (e.g. inbound,outbound)

7. Agents Performance

GET /reports/genesys/agents/performance

Return Genesys agents performance metrics for a time range.

Query Parameters

Parameter Type Required Description
startDate string Yes ISO-8601
endDate string Yes ISO-8601
mediaTypes string No Comma-separated list (e.g. voice,chat)
directions string No Comma-separated list (e.g. inbound,outbound)
debug string No true/false

Contact Us

For support, questions, or more information about Wesal Cloud APIs, please reach out to us:

Support Team

Contact Method Details
Email info@wesalcx.com
Website www.wesalcx.com
Phone +966 11 234 4351

Business Hours

Sunday - Thursday: 9:00 AM - 5:00 PM (GMT+3)

Friday - Saturday: Closed

Note: For urgent technical issues, please include your company ID and a detailed description of the problem in your email.