Wesal Cloud API v1

Complete API Documentation for WesalVoC Platform

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

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 support@wesalcx.com
Website www.wesalcx.com
Phone +966 XX XXX XXXX

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.