# Versalence Backend API # Agency Sync API URI ```bash https://api.versal.one/ ``` 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**
HeaderTypeDescriptionConstraints
`Authorization`StringBearer token for authentication and authorization.Required. Must be in the format `Bearer [token]`.
--- #### **Query Parameters**
ParameterTypeDescriptionConstraints
`uuid`StringUnique identifier for the agency.Required. Must be a valid UUID format.
--- #### **Response Codes**
Status CodeDescription
`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):** ```bash POST /53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/sync Authorization: Bearer 5395b6a27b61 ``` **Response (Sync Complete - 200):** ```json { "status": true, "message": "Sync Complete" } ``` **Response (Missing UUID - 400):** ```json { "success": false, "message": "Bad Request: Missing uuid parameter" } ``` **Response (Invalid HMAC - 403):** ```json { "success": false, "message": "Forbidden: Invalid HMAC signature" } ``` **Response (Not Found - 404):** ```json { "success": false, "message": "No company found with the provided uuid" } ``` **Response (Server Error - 500):** ```json { "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 ```bash https://api.versal.one/ ``` ``` 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**
HeaderTypeDescriptionConstraints
`Authorization`StringBearer token for authentication and authorization.Required. Must be in the format `Bearer [token]`.
--- #### **Query Parameters**
ParameterTypeDescriptionConstraints
`uuid`StringUnique identifier for the agency.Required. Must be a valid UUID format.
--- #### **Request Body Parameters**
FieldTypeDescriptionConstraints
`template_name`StringName of the template to be tracked.Required.
`phone_number`StringPhone number associated with the template.Required.
`wam_id`StringUnique identifier for the WhatsApp template. If not provided, the template will be reported as failed.Optional.
--- #### **Response Codes**
Status CodeDescription
`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):** ```json POST 53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/template Authorization: Bearer 5395b6a27b61 { "template_name": "savetem", "phone_number": "6363978748", "wam_id": "wamkskdfj-lkskfdkskf" } ``` **Response (Success - 200):** ```json { "success": true, "message": "Template data processed successfully" } ``` **Response (Missing UUID - 400):** ```json { "success": false, "message": "Bad Request: Missing uuid parameter" } ``` **Response (Missing Fields - 400):** ```json { "success": false, "message": "Template name and phone number are required" } ``` **Response (Invalid HMAC - 403):** ```json { "success": false, "message": "Forbidden: Invalid HMAC signature" } ``` **Response (No Company Found - 404):** ```json { "success": false, "message": "No company found with the provided uuid" } ``` **Response (MongoDB Failure - 500):** ```json { "success": false, "message": "Failed to save data in MongoDB. Please try again later." } ``` **Response (Unexpected Error - 500):** ```json { "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/ ``` ``` 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**
HeaderTypeDescriptionConstraints
`Authorization`StringBearer token for authentication and authorization.Required. Must be in the format `Bearer [token]`.
--- #### **Query Parameters**
ParameterTypeDescriptionConstraints
`uuid`StringUnique identifier for the agency.Required. Must be a valid UUID format.
--- #### **Request Body Parameters**
FieldTypeDescriptionConstraints
`name`StringCampaign name.Required. Must be unique.
`template_payload`ObjectTemplate details for the campaign.Required. Must include user-defined variables matching `body_variable` and `header_variable`.
`schedule_type`StringType of schedule for the campaign.Required. Allowed values: `"once"`, `"recurring"`.
`days`ObjectDays and times for a recurring schedule.Required for `"recurring"` schedules. Must include days (e.g., `"monday"`) with an array of times.
`schedule`StringDate and time for the campaign.Required. Must follow a valid datetime format.
--- #### **Response Codes**
Status CodeDescription
`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):** ```json 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):** ```json 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):** ```json { "success": true, "message": "Campaign successfully created" } ``` **Response (Missing Variables - 400):** ```json { "success": false, "message": "Name and Template payload are required for the campaign creation" } ``` **Response (Invalid Schedule Type - 400):** ```json { "success": false, "message": "Schedule type should include only 'once' and 'recurring'." } ``` **Response (Days Required for Recurring - 400):** ```json { "success": false, "message": "Days and Times are required for a recurring schedule." } ``` **Response (Conflict - 409):** ```json { "success": false, "message": "Name already exists" } ``` **Response (Internal Server Error - 500):** ```json { "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/ ``` ``` 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**
HeaderTypeDescriptionConstraints
`Authorization`StringJWT token for authentication and authorization.Required. Must be in the format `Bearer [token]`.
--- #### **Query Parameters**
FieldTypeDescriptionConstraints
`uuid`StringUnique identifier for the agency.Required.
`page`IntegerPage number for pagination.Optional. Defaults to 1.
`limit`IntegerNumber of items per page.Optional. Defaults to 10.
--- #### **Response Codes**
Status CodeDescription
`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:** ```json GET 53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/getCampaignData?page=1&limit=10 Authorization: Bearer 5395b6a27b61 ``` **Response (200 - Success):** ```json { "success": true, "message": "Campaigns retrieved successfully.", "data": [ // List of campaigns ], "pagination": { "total": 100, "page": 1, "limit": 10, "totalPages": 10 } } ``` **Response (400 - Invalid Parameters):** ```json { "success": false, "message": "Invalid pagination parameters." } ``` **Response (403 - Forbidden):** ```json { "success": false, "message": "Forbidden: Invalid HMAC signature." } ``` **Response (404 - No Campaigns Found):** ```json { "success": false, "message": "No campaigns found for the given UUID." } ``` **Response (500 - Internal Server Error):** ```json { "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/ ``` ``` GET /agency/getCampaign/ ``` #### **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**
HeaderTypeDescriptionConstraints
`Authorization`StringJWT token for user authentication and authorization.Required. Must be in the format `Bearer [token]`.
--- #### **Request Parameters**
FieldTypeDescriptionConstraints
`id`StringID of the campaign to fetch.Required.
`uuid`StringUUID of the company or user associated with the campaign.Required.
--- #### **Response Codes**
Status CodeDescription
`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):** ```json GET 53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/getCampaign/12345 Authorization: Bearer 5395b6a27b61 ``` **Response (Campaign Found - 200):** ```json { "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):** ```json { "success": true, "message": "No campaign data found.", "data": [] } ``` **Response (Missing Campaign ID - 400):** ```json { "success": false, "message": "Campaign ID is required." } ``` **Response (No Company Found - 404):** ```json { "success": false, "message": "No company found with the provided uuid" } ``` **Response (Internal Server Error - 500):** ```json { "success": false, "message": "An unexpected error occurred while fetching the campaign by id. Please try again later." } ``` **Response (Invalid HMAC Signature - 403):** ```json { "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/ ``` ``` 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**
HeaderTypeDescriptionConstraints
`Authorization`StringJWT token for user authentication and authorization.Required. Must be in the format `Bearer [token]`.
--- #### **Request Parameters**
FieldTypeDescriptionConstraints
`uuid`StringUUID of the company whose customer data is to be fetched.Required.
--- #### **Response Codes**
Status CodeDescription
`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):** ```json GET 53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/getCustomers Authorization: Bearer 5395b6a27b61 ``` **Response (Customer Data Found - 200):** ```json { "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):** ```json { "success": false, "message": "Bad Request: Missing uuid parameter" } ``` **Response (No Company Found - 404):** ```json { "success": false, "message": "No company found with the provided uuid" } ``` **Response (Unable to Fetch Customer Limit - 400):** ```json { "success": false, "message": "Unable to fetch customer limit data" } ``` **Response (Invalid HMAC Signature - 403):** ```json { "success": false, "message": "Forbidden: Invalid HMAC signature" } ``` **Response (Internal Server Error - 500):** ```json { "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/ ``` ``` 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**
HeaderTypeDescriptionConstraints
`Authorization`StringJWT token for user authentication and authorization.Required. Must be in the format `Bearer [token]`.
--- #### **Request Parameters**
FieldTypeDescriptionConstraints
`uuid`StringUUID of the company for which the report is to be fetched.Required.
--- #### **Response Codes**
Status CodeDescription
`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):** ```json GET /53d1bcd3-aaf0-45e1-9298-5395b6a27b61/agency/reportingCampaign Authorization: Bearer 5395b6a27b61 ``` **Response (Report Found - 200):** ```json { "success": true, "message": "Report retrieved successfully.", "data": { "reportId": "12345", "reportName": "Campaign Analysis", "details": "Report details here..." } } ``` **Response (Missing UUID - 400):** ```json { "success": false, "message": "Bad Request: Missing uuid parameter" } ``` **Response (No Company Found - 404):** ```json { "success": false, "message": "No company found with the provided uuid" } ``` **Response (Users Not Found - 404):** ```json { "success": false, "message": "Users not found with the provided uuid" } ``` **Response (Invalid HMAC Signature - 403):** ```json { "success": false, "message": "Forbidden: Invalid HMAC signature" } ``` **Response (Internal Server Error - 500):** ```json { "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.