XFin

Overview

To align with industry standards, Awaaz.De uses REST APIs with simple and flexible architecture leading to easier implementation and integration. Partners need to integrate two APIs:

Login API: JWT-based authentication that allows partners to make a login request once and send multiple message requests using the same token. Partners only need to request login when the token expires. JWT access tokens are valid for 1 hour.
Message API: Used to schedule automated voice call messages to customers.

Demo Code

Awaaz.De’s API integration demo code is available on GitHub and explains how to authenticate via the Login API, obtain a token, and send automated voice calls using the Message API. Demo code is available in:

Contact our team to set up your account.
After account creation, you’ll receive key details like the tenant name, which you’ll need to include in every API request.

Endpoint

POST https://api.awaaz.de/{tenant}/v1/account/login

Request Body

{
  "email": "[email protected]",
  "password": "string"
}

Request Parameters

Parameter	Type	Description
`email`	string	User email for login
`password`	string	User password for login

Success Response

Status Code: 200 OK

{
  "token": "<JWT token which needs to be passed with Message API>",
  "user": {
    // Other user details
  }
}

The JWT token returned is active for 1 hour. This token must be passed with the Message API to successfully authenticate message requests.

Error Response

Status Code: 401 Unauthorized

{
  "non_field_errors": [
    "Unable to log in with provided credentials."
  ]
}

This error indicates an issue with the provided credentials.

Message API

Endpoint

POST https://api.awaaz.de/{tenant}/v1/xact/message/create_bulk

Authentication

Include the JWT token obtained from the Login API in the request headers:

Authorization: Bearer <your-jwt-token>

Request Body

{
  "transform_using_template": true,
  "data": [
    {
      "phone_number": "9099830084",
      "language": "Oriya",
      "day_of_month": "5",
      "installment_amount": "100",
      "month": "may",
      "template": "Payment Confirmation-Late Payers-short",
      "number_of_days": "2",
      "tags": ["clientID", "LAN", "group ID", "state", "branchname"]
    },
    {
      "phone_number": "9805830084",
      "language": "Oriya",
      "day_of_month": "5",
      "installment_amount": "100",
      "month": "may",
      "template": "Payment Confirmation-Late Payers-short",
      "number_of_days": "2",
      "tags": ["clientID", "LAN", "group ID", "state", "branchname"]
    }
  ]
}

Note: Request data should be customized based on your template and language requirements.

Request Parameters

Parameter	Type	Required	Description
`transform_using_template`	boolean	Yes	Enable template-based transformation
`data`	array	Yes	Array of message objects to be scheduled
`instant_message`	boolean	No	Indicates whether the message should be sent immediately. You can schedule up to 5 messages with this flag.

Following parameters are part of data field:

Parameter	Type	Required	Description
`phone_number`	string	Yes	Phone number in international format (e.g., +9194XXXXXXXX)
`language`	string	Yes	Language to be used for the voice call
`template`	string	Yes	Template name (or ID) indicating the script for the call
`tags`	array	No	List of tags or additional metadata for the message

Additional parameters like day_of_month, installment_amount, month, and number_of_days are template-specific and should be included based on your template requirements.

Rate Limits

5,000 messages per request: approximately 30 seconds to process
10,000 messages per request: approximately 45-50 seconds to process

Success Response

Status Code: 201 Created

[
  {
    "phone_number": "9099830084",
    "status": "created",
    "language": "Oriya",
    "templatelanguage": 87,
    "day_of_month": "5",
    "installment_amount": 100,
    "month": 5,
    "template": "Payment Confirmation-Late Payers-short",
    "number_of_days": 2,
    "id": 39937283
  },
  {
    "phone_number": "9805830084",
    "status": "created",
    "language": "Oriya",
    "templatelanguage": 87,
    "day_of_month": "5",
    "installment_amount": 100,
    "month": 5,
    "template": "Payment Confirmation-Late Payers-short",
    "number_of_days": 2,
    "id": 39937284
  }
]

All messages with "status": "created" have been successfully scheduled.

Error Response

Status Code: 201 Created (partial success)

[
  {
    "phone_number": "9805830084",
    "status": "created",
    "language": "Oriya",
    "templatelanguage": 87,
    "day_of_month": "5",
    "installment_amount": 100,
    "month": 5,
    "template": "Payment Confirmation-Late Payers-short",
    "number_of_days": 2,
    "id": 39937287
  },
  {
    "phone_number": "909930084",
    "status": "invalid",
    "language": "Oriya",
    "templatelanguage": 87,
    "day_of_month": "5",
    "installment_amount": 100,
    "month": 5,
    "template": "Payment Confirmation-Late Payers-short",
    "error": "phone_number: Invalid input provided",
    "number_of_days": 2
  }
]

Messages with "status": "invalid" contain errors. The error field provides details about what went wrong.

Example Request and Response

Request

{
  "transform_using_template": true,
  "data": [
    {
      "phone_number": "9099830084",
      "language": "Oriya",
      "day_of_month": "5",
      "installment_amount": "100",
      "month": "may",
      "template": "Payment Confirmation-Late Payers-short",
      "number_of_days": "2",
      "tags": ["clientID", "LAN", "group ID", "state", "branchname"]
    },
    {
      "phone_number": "1234",
      "language": "Oriya",
      "day_of_month": "5",
      "installment_amount": "100",
      "month": "may",
      "template": "Payment Confirmation-Late Payers-short",
      "number_of_days": "2",
      "tags": ["clientID", "LAN", "group ID", "state", "branchname"]
    }
  ]
}

Response

[
  {
    "phone_number": "9099830084",
    "language": "Oriya",
    "day_of_month": "5",
    "installment_amount": "100",
    "month": "may",
    "template": "Payment Confirmation-Late Payers-short",
    "number_of_days": "2",
    "tags": ["clientID", "LAN", "group ID", "state", "branchname"],
    "templatelanguage": 87,
    "id": 39,
    "status": "created"
  },
  {
    "phone_number": "1234",
    "language": "Oriya",
    "day_of_month": "5",
    "installment_amount": "100",
    "month": "may",
    "template": "Payment Confirmation-Late Payers-short",
    "number_of_days": "2",
    "tags": ["clientID", "LAN", "group ID", "state", "branchname"],
    "templatelanguage": 87,
    "error": "phone_number: Invalid input provided",
    "status": "invalid"
  }
]

The first message was successfully created (status: created), while the second message failed due to an invalid phone number (status: invalid).

Error Handling

HTTP Status Codes

Status Code	Description	Action
`200`	The request has succeeded	N/A
`201`	The request has succeeded and a new message has been created	N/A
`400`	Bad Request - Invalid or malformed data	Verify request format matches API documentation. Check the error message for specific data issues
`401`	Unauthorized - User is not authenticated	Please log in using the Login API
`403`	Forbidden - Token expired	Please re-login to obtain a new JWT token
`404`	Not Found - URL is not recognized	Verify the API endpoint URL is correct
`502`	Bad Gateway	Retry the operation after some time. If issue persists after multiple retries, contact Awaaz.De
`504`	Gateway Timeout	Retry the operation after some time. If issue persists after multiple retries, contact Awaaz.De
`500-599`	Server Error	We monitor our systems for such errors. If not resolved within 24 hours, please contact Awaaz.De

Common Error Scenarios

Invalid Credentials

{
  "non_field_errors": [
    "Unable to log in with provided credentials."
  ]
}

Solution: Verify email and password are correct.

Invalid Phone Number

{
  "error": "phone_number: Invalid input provided",
  "status": "invalid"
}

Solution: Ensure phone number is in valid international format (e.g., +9194XXXXXXXX).

Expired Token

Status Code: 403 Forbidden Solution: Re-authenticate using the Login API to obtain a new JWT token.

Best Practices

Token Management: Cache the JWT token and reuse it for multiple requests within the 1-hour validity period. Only request a new token when the current one expires.
Batch Processing: Group messages in batches of up to 10,000 for optimal performance.
Error Handling: Always check the status field in the response for each message. Messages can fail individually while others succeed.
Phone Number Format: Always use international format with country code (e.g., +91 for India).
Retry Logic: Implement exponential backoff for 502, 504, and 5xx errors.
Rate Limiting: Be mindful of processing times when sending large batches of messages.

Support

For technical support or questions about API integration, please contact:

Email: [email protected]

Overview

XACT

Voice AI Hosting

Overview

Demo Code

Endpoint

Request Body

Request Parameters

Success Response

Error Response

Message API

Endpoint

Authentication

Request Body

Request Parameters

Rate Limits

Success Response

Error Response

Example Request and Response

Request

Response

Error Handling

HTTP Status Codes

Common Error Scenarios

Invalid Credentials

Invalid Phone Number

Expired Token

Best Practices

Support

Overview

XACT

Voice AI Hosting

​Overview

​Demo Code

​Login API

​Endpoint

​Request Body

​Request Parameters

​Success Response

​Error Response

​Message API

​Endpoint

​Authentication

​Request Body

​Request Parameters

​Rate Limits

​Success Response

​Error Response

​Example Request and Response

​Request

​Response

​Error Handling

​HTTP Status Codes

​Common Error Scenarios

​Invalid Credentials

​Invalid Phone Number

​Expired Token

​Best Practices

​Support

Overview

Demo Code

Login API

Endpoint

Request Body

Request Parameters

Success Response

Error Response

Message API

Endpoint

Authentication

Request Body

Request Parameters

Rate Limits

Success Response

Error Response

Example Request and Response

Request

Response

Error Handling

HTTP Status Codes

Common Error Scenarios

Invalid Credentials

Invalid Phone Number

Expired Token

Best Practices

Support