Versalence Backend API

by Lokesh Ravi

Agency Sync
Agency Template Reporting
Agency Campaign Creation
Agency Read Campaign
Agency Read Campaign By Id
Agency Get Customers
Agency Get Campaign

Agency Sync

API URI

https://api.versal.one/<uuid>

Method

POST /agency/sync

Description

This API synchronizes agency data using a unique identifier (uuid). The client must provide an authorization token to access this endpoint. The API responds with success, error, or status messages based on the input and server-side processes.

Request Headers

Header	Type	Description	Constraints
`Authorization`	String	Bearer token for authentication and authorization.	Required. Must be in the format `Bearer [token]`.

Query Parameters

Parameter	Type	Description	Constraints
`uuid`	String	Unique identifier for the agency.	Required. Must be a valid UUID format.

Response Codes

Status Code	Description
`200`	Sync completed successfully. Returns a success message.
`400`	Bad request. The `uuid` parameter is missing or invalid.
`403`	Access forbidden. Invalid HMAC signature.
`404`	No agency found with the provided `uuid`.
`500`	Internal server error. Something went wrong on the backend.

Example Requests

Request (Sync Agency):

 POST /53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/sync
 Authorization: Bearer 5395b6a27b61

Response (Sync Complete - 200):

 { "status": true, "message": "Sync Complete" }

Response (Missing UUID - 400):

 { "success": false, "message": "Bad Request: Missing uuid parameter" }

Response (Invalid HMAC - 403):

 { "success": false, "message": "Forbidden: Invalid HMAC signature" }

Response (Not Found - 404):

 { "success": false, "message": "No company found with the provided uuid" }

Response (Server Error - 500):

 { "status": false, "message": "Something went wrong on the backend" }

Notes

Authentication: The authorization token must be valid. If it is missing or invalid, the request will fail.
Field Validation: Ensure the uuid parameter is correctly formatted as a valid UUID.
Error Handling: For 500 errors, consult server logs for debugging.

Agency Template Reporting

API URI

https://api.versal.one/<uuid>

POST /agency/template

Description

This API enables agencies to submit and track template information. The client must provide a valid uuid as a query parameter and include the template details in the request body. If the wam_id is not provided, the template will automatically be reported as failed.

Request Headers

Header	Type	Description	Constraints
`Authorization`	String	Bearer token for authentication and authorization.	Required. Must be in the format `Bearer [token]`.

Query Parameters

Parameter	Type	Description	Constraints
`uuid`	String	Unique identifier for the agency.	Required. Must be a valid UUID format.

Request Body Parameters

Field	Type	Description	Constraints
`template_name`	String	Name of the template to be tracked.	Required.
`phone_number`	String	Phone number associated with the template.	Required.
`wam_id`	String	Unique identifier for the WhatsApp template. If not provided, the template will be reported as failed.	Optional.

Response Codes

Status Code	Description
`403`	Forbidden. Invalid HMAC signature.
`400`	Bad request. Missing `uuid` parameter or required fields in the request body.
`404`	No company found with the provided `uuid`.
`500`	Failed to save data to MongoDB or process the template data.

Example Requests

Request (Track Template):

 POST 53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/template
 Authorization: Bearer 5395b6a27b61
 {
  "template_name": "savetem",
  "phone_number": "6363978748",
  "wam_id": "wamkskdfj-lkskfdkskf"
 }

Response (Success - 200):

 { "success": true, "message": "Template data processed successfully" }

Response (Missing UUID - 400):

 { "success": false, "message": "Bad Request: Missing uuid parameter" }

Response (Missing Fields - 400):

 { "success": false, "message": "Template name and phone number are required" }

Response (Invalid HMAC - 403):

 { "success": false, "message": "Forbidden: Invalid HMAC signature" }

Response (No Company Found - 404):

 { "success": false, "message": "No company found with the provided uuid" }

Response (MongoDB Failure - 500):

 { "success": false, "message": "Failed to save data in MongoDB. Please try again later." }

Response (Unexpected Error - 500):

 { "success": false, "message": "An unexpected error occurred while processing the template data. Please try again later." }

Notes

Authentication: The authorization token must be valid and properly formatted. Invalid or missing tokens will result in a 403 error.
Field Validation: The template_name and phone_number fields are required for this request.
WAM ID Handling: If wam_id is not provided, the template will automatically be reported as failed.
Error Handling: For 500 errors, consult server logs for more details.

Agency Campaign Creation

API URI

https://api.versal.one/<uuid>

POST /agency/createCampaign

Description

This API allows agencies to create a campaign by specifying a name, schedule type, and other campaign details. The client must provide a valid uuid as a query parameter. Only accepted variables will be processed, and all user-defined variables must match the expected format.

Request Headers

Header	Type	Description	Constraints
`Authorization`	String	Bearer token for authentication and authorization.	Required. Must be in the format `Bearer [token]`.

Query Parameters

Parameter	Type	Description	Constraints
`uuid`	String	Unique identifier for the agency.	Required. Must be a valid UUID format.

Request Body Parameters

Field	Type	Description	Constraints
`name`	String	Campaign name.	Required. Must be unique.
`template_payload`	Object	Template details for the campaign.	Required. Must include user-defined variables matching `body_variable` and `header_variable`.
`schedule_type`	String	Type of schedule for the campaign.	Required. Allowed values: `"once"`, `"recurring"`.
`days`	Object	Days and times for a recurring schedule.	Required for `"recurring"` schedules. Must include days (e.g., `"monday"`) with an array of times.
`schedule`	String	Date and time for the campaign.	Required. Must follow a valid datetime format.

Response Codes

Status Code	Description
`201`	Campaign successfully created.
`400`	Bad request. Missing required fields, invalid `schedule_type`, or user-defined variables mismatch.
`403`	Forbidden. Invalid HMAC signature.
`404`	No company found with the provided `uuid`.
`409`	Conflict. Campaign name already exists.
`500`	Internal server error while saving the campaign.

Example Requests

Request (Carousel Template):

 POST /53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/createCampaign
 Authorization: Bearer 5395b6a27b61
 {
  "name": "temp3",
  "template_payload": {
    "cards": [
      {
        "card_image_url": "https://example.com/image1.jpg",
        "card_body_variables": []
      },
      {
        "card_image_url": "https://example.com/image2.jpg",
        "card_body_variables": []
      }
    ],
    "image_url": "",
    "group_name": "test_group",
    "body_variable": [],
    "template_name": "carousel_milk",
    "header_variable": []
  },
  "schedule_type": "recurring",
  "days": {
    "monday": [
      "10:00"
    ],
    "wednesday": [
      "10:00"
    ]
  },
  "schedule": "2025-01-15 14:50"
}

Request (Header and Body Variables):

 POST /53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/createCampaign
 Authorization: Bearer 5395b6a27b61
 {
  "name": "temp3",
  "template_payload": {
    "image_url": "",
    "group_name": "Team Testing",
    "body_variable": [
      "world"
    ],
    "template_name": "test_template_1",
    "header_variable": [
      "hello"
    ]
  },
  "schedule_type": "once",
  "schedule": "2025-01-15 14:50"
}

Response (Created - 201):

 { "success": true, "message": "Campaign successfully created" }

Response (Missing Variables - 400):

 { "success": false, "message": "Name and Template payload are required for the campaign creation" }

Response (Invalid Schedule Type - 400):

 { "success": false, "message": "Schedule type should include only 'once' and 'recurring'." }

Response (Days Required for Recurring - 400):

 { "success": false, "message": "Days and Times are required for a recurring schedule." }

Response (Conflict - 409):

 { "success": false, "message": "Name already exists" }

Response (Internal Server Error - 500):

 { "success": false, "message": "An unexpected error occurred while saving the campaign. Please try again later." }

Notes

Authentication: A valid authorization token is required for all requests.
Validation: All user-defined variables must exactly match the template's body_variable and header_variable.
Recurring Schedules: days and times must be included for recurring schedules; otherwise, the request will fail.
Conflict Handling: Campaign names must be unique.

Agency Read Campaign

API URI

https://api.versal.one/<uuid>

GET /agency/getCampaignData

Description

This API retrieves campaign data for a specified agency using a unique identifier (uuid). It supports pagination for large datasets. A valid JWT token is mandatory for authentication and authorization.

Request Headers

Header	Type	Description	Constraints
`Authorization`	String	JWT token for authentication and authorization.	Required. Must be in the format `Bearer [token]`.

Query Parameters

Field	Type	Description	Constraints
`uuid`	String	Unique identifier for the agency.	Required.
`page`	Integer	Page number for pagination.	Optional. Defaults to 1.
`limit`	Integer	Number of items per page.	Optional. Defaults to 10.

Response Codes

Status Code	Description
`200`	Success. Campaigns retrieved successfully.
`400`	Invalid pagination parameters or missing `uuid` parameter.
`403`	Forbidden: Invalid HMAC signature.
`404`	No campaigns found for the provided `uuid` or no company associated with the `uuid`.
`500`	An unexpected error occurred while fetching the campaigns.

Example Requests

Request:


GET 53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/getCampaignData?page=1&limit=10
Authorization: Bearer 5395b6a27b61

Response (200 - Success):


{
  "success": true,
  "message": "Campaigns retrieved successfully.",
  "data": [
    // List of campaigns
  ],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10
  }
}

Response (400 - Invalid Parameters):


{
  "success": false,
  "message": "Invalid pagination parameters."
}

Response (403 - Forbidden):


{
  "success": false,
  "message": "Forbidden: Invalid HMAC signature."
}

Response (404 - No Campaigns Found):


{
  "success": false,
  "message": "No campaigns found for the given UUID."
}

Response (500 - Internal Server Error):


{
  "success": false,
  "message": "An unexpected error occurred while fetching the campaigns.",
  "error": "Error details here"
}

Notes

Authentication: Ensure the JWT token is valid. Invalid or missing tokens will result in a 403 or 401 error.
Field Validation: The uuid field is mandatory for this request.
Error Handling: Review server logs for debugging 500 errors.
Pagination: If the page or limit is invalid, a 400 error is returned.

Agency Read Campaign By Id

API URI

https://api.versal.one/<uuid>

GET /agency/getCampaign/<campaign id>

Description

This API allows fetching campaign details by providing the campaign id and the uuid of the company. The endpoint returns campaign data if found, otherwise, a message indicating no data found.

Request Headers

Header	Type	Description	Constraints
`Authorization`	String	JWT token for user authentication and authorization.	Required. Must be in the format `Bearer [token]`.

Request Parameters

Field	Type	Description	Constraints
`id`	String	ID of the campaign to fetch.	Required.
`uuid`	String	UUID of the company or user associated with the campaign.	Required.

Response Codes

Status Code	Description
`200`	Success. Campaign data retrieved successfully.
`204`	No Content. No campaign found for the provided ID.
`400`	Bad Request. Campaign ID is required.
`401`	Unauthorized. Invalid or missing JWT token.
`404`	Not Found. No company found with the provided UUID or no campaign found with the ID.
`500`	Internal Server Error. An unexpected error occurred while fetching the campaign data.
`403`	Forbidden. Invalid HMAC signature.

Example Requests

Request (Get Campaign):


GET 53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/getCampaign/12345
Authorization: Bearer 5395b6a27b61

Response (Campaign Found - 200):


{
  "success": true,
  "message": "Successfully fetched campaign data.",
  "data": [
    {
      "id": "12345",
      "uuid": "53d1bcd3-aaf0-45e1-9298-5395b6a27b61",
      "name": "Campaign Name",
      "status": "active",
      "startDate": "2025-01-01",
      "endDate": "2025-12-31"
    }
  ]
}

Response (No Campaign Found - 204):


{
  "success": true,
  "message": "No campaign data found.",
  "data": []
}

Response (Missing Campaign ID - 400):


{
  "success": false,
  "message": "Campaign ID is required."
}

Response (No Company Found - 404):


{
  "success": false,
  "message": "No company found with the provided uuid"
}

Response (Internal Server Error - 500):


{
  "success": false,
  "message": "An unexpected error occurred while fetching the campaign by id. Please try again later."
}

Response (Invalid HMAC Signature - 403):


{
  "success": false,
  "message": "Forbidden: Invalid HMAC signature"
}

Notes

Authentication: Ensure the JWT token is valid and authorized to access campaign data.
Validation: Both id and uuid are required. Missing any of these will result in a 400 or 404 error.
Error Handling: For any server errors (500), check the logs for detailed error information.

Agency Get Customers

API URI

https://api.versal.one/<uuid>

GET /agency/getCustomers

Description

This API allows fetching customer data for a specific company identified by its uuid. It returns customer information along with pagination details, such as the next and previous pages, if applicable.

Request Headers

Header	Type	Description	Constraints
`Authorization`	String	JWT token for user authentication and authorization.	Required. Must be in the format `Bearer [token]`.

Request Parameters

Field	Type	Description	Constraints
`uuid`	String	UUID of the company whose customer data is to be fetched.	Required.

Response Codes

Status Code	Description
`200`	Success. Customer data retrieved successfully.
`403`	Forbidden. Invalid HMAC signature.
`400`	Bad Request. Missing `uuid` parameter or unable to fetch customer limit data.
`404`	Not Found. No company found with the provided UUID.
`500`	Internal Server Error. An unexpected error occurred while fetching customer data.

Example Requests

Request (Get Customers):


GET 53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/getCustomers
Authorization: Bearer 5395b6a27b61

Response (Customer Data Found - 200):


{
  "success": true,
  "message": "Customer data fetched successfully",
  "data": [
    {
      "id": "123",
      "name": "Customer A",
      "email": "customerA@example.com"
    },
    {
      "id": "124",
      "name": "Customer B",
      "email": "customerB@example.com"
    }
  ],
  "paging": {
    "before": 1,
    "after": 3
  }
}

Response (Missing UUID - 400):


{
  "success": false,
  "message": "Bad Request: Missing uuid parameter"
}

Response (No Company Found - 404):


{
  "success": false,
  "message": "No company found with the provided uuid"
}

Response (Unable to Fetch Customer Limit - 400):


{
  "success": false,
  "message": "Unable to fetch customer limit data"
}

Response (Invalid HMAC Signature - 403):


{
  "success": false,
  "message": "Forbidden: Invalid HMAC signature"
}

Response (Internal Server Error - 500):


{
  "success": false,
  "message": "An unexpected error occurred while fetching the customers. Please try again later.",
  "error": "Error details here"
}

Notes

Authentication: Ensure the JWT token is valid and authorized to access customer data.
Validation: The uuid is a required parameter. Ensure it's included in the request.
Error Handling: For any server errors (500), check the logs for detailed error information.
Paging: The response includes paging information to navigate through customer data.

Agency Get Campaign

API URL

https://api.versal.one/<uuid>

GET /agency/reportingCampaign

Description

This API allows fetching a report for a specific company, identified by its uuid. The response contains the report data if available. If the company or users are not found, the appropriate error message is returned.

Request Headers

Header	Type	Description	Constraints
`Authorization`	String	JWT token for user authentication and authorization.	Required. Must be in the format `Bearer [token]`.

Request Parameters

Field	Type	Description	Constraints
`uuid`	String	UUID of the company for which the report is to be fetched.	Required.

Response Codes

Status Code	Description
`200`	Success. Report data retrieved successfully.
`403`	Forbidden. Invalid HMAC signature.
`400`	Bad Request. Missing `uuid` parameter.
`404`	Not Found. No company found with the provided UUID or users not found for the given UUID.
`500`	Internal Server Error. An error occurred while fetching the report.

Example Requests

Request (Get Reporting Campaign):


GET /53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/reportingCampaign
Authorization: Bearer 5395b6a27b61

Response (Report Found - 200):


{
  "success": true,
  "message": "Report retrieved successfully.",
  "data": {
    "reportId": "12345",
    "reportName": "Campaign Analysis",
    "details": "Report details here..."
  }
}

Response (Missing UUID - 400):


{
  "success": false,
  "message": "Bad Request: Missing uuid parameter"
}

Response (No Company Found - 404):


{
  "success": false,
  "message": "No company found with the provided uuid"
}

Response (Users Not Found - 404):


{
  "success": false,
  "message": "Users not found with the provided uuid"
}

Response (Invalid HMAC Signature - 403):


{
  "success": false,
  "message": "Forbidden: Invalid HMAC signature"
}

Response (Internal Server Error - 500):


{
  "success": false,
  "message": "An error occurred while fetching the report.",
  "error": "Error details here"
}

Notes

Authentication: Ensure the JWT token is valid and authorized to access the reporting campaign data.
Validation: The uuid parameter is required and should be provided in the request URL.
Error Handling: If a 500 error occurs, check the error logs for details on what went wrong during the report retrieval process.