Skip to main content

Frequently Asked Questions

Find answers to common questions about the Qlara Partner Gateway API. For additional support, contact our team.

Authentication​

What authentication method should I use?​

We recommend using API Key authentication for all requests. API Key authentication is secure, simple to implement, and provides clear audit trails for your API usage.

Include your API key in the X-Api-Key header:

X-Api-Key: your_api_key_here

Where can I find my API key?​

Your API key is available in your Qlara Partner Gateway dashboard under Account Settings. You can find it in the "API Keys" section.

Can I have multiple API keys?​

Yes, you can create multiple API keys for different applications or environments. Each key can be managed independently with its own permissions and can be revoked without affecting other keys.

To create additional keys:

  1. Navigate to Account Settings → API Keys
  2. Click "Generate New Key"
  3. Give your key a descriptive name
  4. Copy the key immediately (you won't be able to view it again)

Is my API key sensitive?​

Yes, treat your API key like a password. Never share it or commit it to version control. If you believe a key has been compromised, revoke it immediately in your dashboard and generate a new one.

Sending Messages​

What's the difference between "accepted" and "delivered"?​

  • Accepted: The message has been successfully accepted by the carrier/provider and is queued for delivery. This happens quickly (usually within seconds).
  • Delivered: The message has been successfully delivered to the recipient's device. This is confirmed via webhook callback and may take longer depending on network conditions.

Always use delivery webhooks to confirm actual delivery to the end user.

Can I send WhatsApp messages without templates?​

Yes, you can send free-form WhatsApp messages outside of templates. However, free-form messages are only valid within a 24-hour window after the customer has engaged with your business.

After 24 hours of inactivity, you must use an approved template to send messages.

How does RCS fallback work?​

RCS (Rich Communication Services) fallback allows your message to automatically attempt delivery via RCS if WhatsApp delivery fails.

Enable RCS fallback by setting fallbackRcs: true in your send request:

\{
  "destination": "+39XXXXXXXXXX",
  "body": "Your message",
  "fallbackRcs": true
\}

If WhatsApp is unavailable for the recipient, the message automatically routes to RCS instead.

Tracked links allow you to monitor message engagement and click-through rates. Use the \{shortLinkT1\} placeholder in your messages:

Click here to learn more: \{shortLinkT1\}

The placeholder is automatically replaced with a short, tracked URL that records clicks and provides analytics.

What's the difference between Universal SMS and Legacy SMS?​

  • Universal SMS: Modern SMS delivery with support for Unicode characters and longer messages. Works globally with consistent delivery rates.
  • Legacy SMS: Traditional SMS with support for basic ASCII characters only. Used for backward compatibility with older systems.

Universal SMS is recommended for new implementations.

Templates​

How long does WhatsApp template approval take?​

Meta typically approves WhatsApp templates within 24 hours. Some templates may be approved faster (within minutes), while others may take longer depending on content complexity and review volume.

During peak times, approval may take up to 48 hours.

Can I modify an approved WhatsApp template?​

Yes, you can modify approved templates, but the changes require a new approval cycle. Modified templates are treated as new templates and must be re-approved by Meta before use.

To modify a template:

  1. Use the Update Template endpoint
  2. Submit the modified template for approval
  3. Wait for Meta approval
  4. Deploy the updated template when approved

What are RCS template types?​

RCS supports multiple template types:

  • Text Templates: Simple text-based messages
  • Card Templates: Rich cards with images, titles, and action buttons
  • Carousel Templates: Multiple cards in a scrollable carousel
  • Form Templates: Interactive forms with input fields

RCS templates are more flexible than WhatsApp templates and support richer formatting.

Webhooks​

How do I configure my callback URL?​

Configure your callback URL in the Qlara Partner Gateway dashboard:

  1. Go to Account Settings → Webhooks
  2. Enter your callback URL (must be HTTPS)
  3. Save the configuration
  4. Test the webhook connection

Your callback URL will receive POST requests with delivery status updates and incoming messages.

What's the INBOUND callback?​

The INBOUND callback notifies you when a customer replies to your message or sends a new message to your business.

This allows you to:

  • Implement conversational flows
  • Track customer engagement
  • Route messages to appropriate teams
  • Build interactive experiences

How long are media URLs valid in webhooks?​

Media URLs included in webhook payloads are valid for a configurable duration. By default, media URLs expire after 180 minutes (3 hours).

This is controlled by the expireMinutes parameter in your account settings. Ensure you download or process media within the validity window.

What should I do if I miss a webhook?​

Webhooks may occasionally fail due to network issues or timeout. Implement the following best practices:

  • Retry Logic: Your callback endpoint should handle retries and timeouts gracefully
  • Polling: Use status polling endpoints as a backup if webhooks fail
  • Idempotency: Design your system to handle duplicate webhook deliveries safely
  • Logging: Log all webhook events for audit and debugging purposes

Error Codes​

What do the HTTP status codes mean?​

CodeStatusDescription
200OKRequest succeeded; message sent successfully
400Bad RequestRequest is invalid (missing required fields, wrong format, etc.)
401UnauthorizedAPI key is missing, invalid, or expired
403ForbiddenYou don't have permission to access this resource or phone number
404Not FoundThe requested resource doesn't exist (invalid template, phone number, etc.)
422Unprocessable EntityRequest is well-formed but contains semantic errors (invalid phone format, etc.)
429Too Many RequestsRate limit exceeded; wait before retrying
500Server ErrorInternal server error; our team has been notified

How should I handle rate limiting?​

When you receive a 429 Too Many Requests response, wait before retrying:

  1. Check the Retry-After header for the recommended wait time
  2. Implement exponential backoff: wait 1 second, then 2 seconds, then 4 seconds, etc.
  3. Set a maximum wait time (e.g., 5 minutes) before giving up
  4. Log rate limit events to identify usage patterns

What causes a 422 Unprocessable Entity error?​

A 422 error indicates the request is well-formed but contains invalid data:

  • Invalid phone number format (missing country code, incorrect length)
  • Template variables don't match template parameters
  • Destination phone number not whitelisted (in test mode)
  • Media file format not supported
  • File size exceeds limits

Check the error details in the response for specific information.

How do I debug a 400 Bad Request error?​

A 400 error means the request is malformed. Common causes:

  • Missing required fields (destination, phoneNumberId, etc.)
  • JSON syntax errors
  • Incorrect data types (e.g., number instead of string)
  • Empty or null values in required fields

Verify your request matches the API specification and includes all required fields.

General Questions​

What messaging channels does Qlara support?​

Qlara supports multiple messaging channels:

  • WhatsApp Business API
  • RCS (Rich Communication Services)
  • SMS
  • Email (via partner integrations)
  • Push notifications (via partner integrations)

You can configure fallback chains to automatically use alternate channels if your primary channel is unavailable.

Is there a message delivery guarantee?​

We provide best-effort delivery with high reliability. However, message delivery depends on:

  • Recipient network connectivity
  • Carrier availability
  • Phone number validity
  • Message content compliance

Monitor delivery webhooks to confirm delivery. If delivery fails, fallback chains automatically route to alternate channels.

What's the maximum message length?​

Maximum message length depends on the channel:

  • WhatsApp: 4,096 characters per message
  • RCS: 1,024 characters (may vary by carrier)
  • SMS: 160 characters (UTF-8 characters count as multiple bytes)
  • Email: No strict limit, but keep subject lines under 100 characters

Can I send messages in different languages?​

Yes, all channels support multiple languages. When using templates, specify the language:

\{
  "template": \{
    "name": "greeting",
    "language": "it"
  \}
\}

Ensure your message content and media are appropriate for the target language and region.

How do I handle opt-in/opt-out compliance?​

Qlara supports multiple regulatory compliance frameworks:

  • GDPR (European Union): Obtain explicit consent before sending promotional messages
  • CCPA (California): Honor opt-out requests within 10 days
  • Regional SMS regulations: Comply with carrier-specific requirements

Manage opt-in/opt-out lists in your account settings or via API endpoints.

Is there a sandbox/test environment?​

Yes, use test phone numbers in development mode to send test messages without charges. Contact support to enable test mode for your account.

In test mode:

  • Only whitelisted test numbers can receive messages
  • No charges are incurred
  • Full API functionality is available
  • Webhooks work normally

How do I monitor API usage?​

Monitor your API usage in the dashboard:

  1. Go to Analytics → API Usage
  2. View requests, delivery rates, and message costs
  3. Set usage alerts and quotas
  4. Export usage reports

Support & Contact​

For additional questions or technical support: