Wesal Cloud API Documentation

Complete API Documentation for WesalVoC Platform

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
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"],
    "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": "37e4be421508c0e91f59d752",
    "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",
            "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",
            "answers": {
                "ServiceSatisfaction": "3",
                "AgentSatisfaction": "4"
            }
        }
    ],
    "total": 2,
    "pageTotal": 2,
    "result": "success"
}

3. 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": "37e4be421508c0e91f59d752",
    "method": "email",
    "email": "user@example.com",
    "phone": "NO"
}

Response

200 OK

Example Response

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

4. 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": "37e4be421508c0e91f59d752",
    "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"
}

5. 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

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.