# Get Project Info
Source: https://docs.otpiq.com/api-reference/endpoint/get
GET /info
Retrieve information about the authenticated project including remaining credits and project details.
# Introduction
Source: https://docs.otpiq.com/api-reference/introduction
OTPIQ API reference guide
## Welcome to OTPIQ API
This is the complete API reference guide for OTPIQ. Here you'll find all the information you need to integrate with our services.
## Authentication
All OTPIQ API endpoints require authentication using your API key. Include your API key in the Authorization header of every request.
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
Keep your API key secure and never expose it in client-side code or public
repositories.
# International SMS Pricing
Source: https://docs.otpiq.com/api-reference/messaging/international-sms-pricing
GET /international-sms-pricing
Paginated international SMS price rows. Each item's `price` is the billed amount in IQD per one SMS segment (one 140-character segment)
# Send SMS
Source: https://docs.otpiq.com/api-reference/messaging/post
POST /sms
Send an SMS message. Supports both verification codes and custom messages with multiple provider options.
# Track SMS
Source: https://docs.otpiq.com/api-reference/messaging/track
GET /sms/track/{smsId}
Get the delivery status of a specific SMS message.
# Generate Delivery Report
Source: https://docs.otpiq.com/api-reference/reports/generate
POST /reports/generate
Create CSV delivery reports for SMS/messages in a date range
Use the `downloadUrl` from the response to download the CSV file directly. There is no separate download endpoint—reports are available for **30 days** after generation.
## CSV content
The downloaded CSV includes these columns:
| Column | Description |
| --------------- | --------------------------------------------------- |
| Message ID | Internal message identifier (`smsId`) |
| Phone Number | Recipient phone number |
| Sender ID | Sender ID name (or "System") |
| Cost (IQD) | Cost in IQD |
| Message Type | OTP, Custom, WhatsApp Template, or Other |
| Delivery Status | `pending`, `sent`, `delivered`, `read`, or `failed` |
| Error Reason | Last error in the message flow (empty if none) |
| Refunded | Yes/No |
| Created At | ISO 8601 |
| Sent At | ISO 8601 (if sent) |
# List Delivery Reports
Source: https://docs.otpiq.com/api-reference/reports/list
GET /reports
Returns a paginated list of delivery reports for the authenticated project, sorted by creation date (newest first). Each report includes `downloadUrl` for direct download; there is no download-by-id endpoint.
# Get Sender IDs
Source: https://docs.otpiq.com/api-reference/sender-id/get
GET /sender-ids
Retrieve all sender IDs associated with the authenticated project.
# Attach Recipients
Source: https://docs.otpiq.com/api-reference/whatsapp/campaigns/attach-recipients
POST /whatsapp/campaigns/{_id}/recipients
Append recipients to a draft or scheduled campaign
This endpoint **appends** new recipients to the existing list.
* Phone numbers already on the campaign are skipped.
* Duplicates within the same request are deduplicated.
* A campaign can have a maximum of **1000** recipients total. If appending would exceed this limit, a `400` error is returned.
* If every number in your request already exists on the campaign, a `400` error is returned.
# Create Campaign
Source: https://docs.otpiq.com/api-reference/whatsapp/campaigns/create
POST /whatsapp/campaigns
Create a new WhatsApp campaign shell without recipients
This endpoint creates the campaign shell. You must add recipients using the [Attach Recipients](/api-reference/whatsapp/campaigns/attach-recipients) endpoint before starting the campaign.
# Delete Campaign
Source: https://docs.otpiq.com/api-reference/whatsapp/campaigns/delete
DELETE /whatsapp/campaigns/{_id}
Delete a draft or scheduled campaign
# Get Campaign Details
Source: https://docs.otpiq.com/api-reference/whatsapp/campaigns/get
GET /whatsapp/campaigns/{_id}
Retrieve campaign details and monitor recipient delivery status
# Get Recipient Schema
Source: https://docs.otpiq.com/api-reference/whatsapp/campaigns/get-recipient-payload
GET /whatsapp/campaigns/recipient-payload
Get the required JSON schema for building the recipient payload for a specific template
Use this endpoint to understand the exact shape of the `templateParameters` required for your chosen template before attaching recipients.
# List Campaigns
Source: https://docs.otpiq.com/api-reference/whatsapp/campaigns/list
GET /whatsapp/campaigns
Retrieve a paginated list of your WhatsApp campaigns
# Send Sample
Source: https://docs.otpiq.com/api-reference/whatsapp/campaigns/send-sample
POST /whatsapp/campaigns/{_id}/sample
Create and immediately start a child sample campaign from a draft or scheduled main campaign
Sending a sample campaign does not modify the parent campaign. It's a great way to test your template and parameters before a full broadcast.
# Start Campaign
Source: https://docs.otpiq.com/api-reference/whatsapp/campaigns/start
POST /whatsapp/campaigns/{_id}/start
Reserve project credits and enqueue the campaign for sending
Once started, the campaign status will change to `running` and messages will begin sending.
# Update Campaign
Source: https://docs.otpiq.com/api-reference/whatsapp/campaigns/update
PATCH /whatsapp/campaigns/{_id}
Update metadata for a draft or scheduled campaign
You can only edit campaigns that are in `draft` or `scheduled` status. Campaigns that have already started cannot be modified.
# List WhatsApp Resources
Source: https://docs.otpiq.com/api-reference/whatsapp/resources
GET /whatsapp/resources
Discover connected WhatsApp businesses, WABAs, phone numbers, and message templates for your project
For large integrations, start with `includeTemplateComponents=false` and only request full template components when you need to render or inspect template structure.
# How Webhooks Work
Source: https://docs.otpiq.com/essentials/how-webhook-works
OTPIQ allows you to configure webhooks for your SMS messages to receive real-time delivery status updates.
OTPIQ webhooks provide real-time delivery status notifications for your SMS messages. When you configure webhooks, you'll receive instant updates about message delivery status directly to your server, without needing to poll the API.
## Webhook Overview
Webhooks are HTTP POST requests that OTPIQ sends to your specified endpoint whenever there's a status update for your SMS messages. This allows you to:
* Get real-time delivery confirmations
* Track message failures immediately
* Update your application's status in real-time
* Avoid the need for constant API polling
## How to Configure Webhooks
To enable webhooks, include a `deliveryReport` object in your SMS request:
```json theme={null}
{
"phoneNumber": "964750123456",
"smsType": "verification",
"verificationCode": "123456",
"senderId": "OTPIQ",
"deliveryReport": {
"webhookUrl": "https://your-app.com/webhooks/sms-status",
"deliveryReportType": "all",
"webhookSecret": "your_secret_123"
}
}
```
## Webhook Configuration Fields
The HTTPS URL where delivery status updates will be sent. Must use HTTPS
protocol. Example: `https://your-app.com/webhooks/sms-status`
Controls when webhooks are triggered: - `"all"` - Receive webhooks for all
status updates (sent, delivered, failed) - `"final"` - Only receive webhooks
for final status updates (delivered or failed)
Optional secret key for webhook authentication. This will be sent in the
`X-OTPIQ-Webhook-Secret` header for security verification. Example:
`your_webhook_secret_123`
## Webhook Payload Structure
Each webhook request contains a JSON payload with the following structure:
### Required Fields
Unique message identifier that matches the ID returned when you sent the SMS.
Example: `sms_1234567890abcdef`
Your configured report type (`"all"` or `"final"`).
Whether this is the final status update for this message. When `true`, no
further webhooks will be sent for this message.
The messaging channel used: `"sms"`, `"whatsapp"`, or `"telegram"`.
Current delivery status: - `"sent"` - Message has been sent to the provider -
`"delivered"` - Message confirmed delivered to recipient - `"failed"` -
Message could not be delivered
### Optional Fields
Failure reason (only included when status is `"failed"`). Example: `"Carrier
rejected the message"`
Sender ID used (included when a custom sender ID was provided for any message
type). Example: `"OTPIQ"`
## Delivery Status Flow
### SMS Messages
1. **sent** → Message accepted by carrier
2. **delivered** → Message confirmed delivered to recipient
3. **failed** → Message could not be delivered
### WhatsApp Messages
1. **sent** → Message sent to WhatsApp servers
2. **delivered** → Message delivered to recipient's device
3. **failed** → Message could not be sent or delivered
### Telegram Messages
1. **sent** → Message sent to Telegram servers
2. **delivered** → Message delivered to recipient
3. **failed** → Message could not be sent
## Webhook Examples
### Example 1: SMS with Custom Sender ID
**Request:**
```json theme={null}
{
"phoneNumber": "964750123456",
"smsType": "custom",
"customMessage": "Your order has been confirmed!",
"senderId": "OTPIQ",
"deliveryReport": {
"webhookUrl": "https://your-app.com/webhooks/sms-status",
"deliveryReportType": "all",
"webhookSecret": "your_secret_123"
}
}
```
**Webhook Payloads Received:**
1. **Sent Status:**
```json theme={null}
{
"smsId": "sms_1234567890abcdef",
"deliveryReportType": "all",
"isFinal": false,
"channel": "sms",
"status": "sent",
"senderId": "OTPIQ"
}
```
2. **Delivered Status:**
```json theme={null}
{
"smsId": "sms_1234567890abcdef",
"deliveryReportType": "all",
"isFinal": true,
"channel": "sms",
"status": "delivered",
"senderId": "OTPIQ"
}
```
### Example 2: WhatsApp with Final-Only Reports
**Request:**
```json theme={null}
{
"phoneNumber": "964750123456",
"smsType": "verification",
"verificationCode": "123456",
"provider": "whatsapp",
"deliveryReport": {
"webhookUrl": "https://your-app.com/webhooks/whatsapp-status",
"deliveryReportType": "final"
}
}
```
**Webhook Payload (Final Status Only):**
```json theme={null}
{
"smsId": "sms_1234567890abcdef",
"deliveryReportType": "final",
"isFinal": true,
"channel": "whatsapp",
"status": "delivered"
}
```
### Example 3: Verification with WhatsApp Custom Sender
**Request:**
```json theme={null}
{
"phoneNumber": "964750123456",
"smsType": "verification",
"verificationCode": "123456",
"whatsappAccountId": "68c46fecc509cdcec8fb3ef2",
"whatsappPhoneId": "68da31fb518ac3db3eb0a0f4",
"templateName": "verification_template",
"provider": "whatsapp",
"deliveryReport": {
"webhookUrl": "https://your-app.com/webhooks/whatsapp-status",
"deliveryReportType": "all"
}
}
```
**Webhook Payloads Received:**
1. **Sent Status:**
```json theme={null}
{
"smsId": "sms_1234567890abcdef",
"deliveryReportType": "all",
"isFinal": false,
"channel": "whatsapp",
"status": "sent"
}
```
2. **Delivered Status:**
```json theme={null}
{
"smsId": "sms_1234567890abcdef",
"deliveryReportType": "all",
"isFinal": true,
"channel": "whatsapp",
"status": "delivered"
}
```
### Example 4: Failed Message
**Request:**
```json theme={null}
{
"phoneNumber": "964750123456",
"smsType": "custom",
"customMessage": "Your order has been confirmed!",
"senderId": "OTPIQ",
"deliveryReport": {
"webhookUrl": "https://your-app.com/webhooks/sms-status",
"deliveryReportType": "final"
}
}
```
**Webhook Payload (Failure):**
```json theme={null}
{
"smsId": "sms_abcdef1234567890",
"deliveryReportType": "final",
"isFinal": true,
"channel": "sms",
"status": "failed",
"reason": "Carrier rejected the message",
"senderId": "OTPIQ"
}
```
## Security Best Practices
Always implement proper security measures when handling webhooks to protect
your application.
### 1. Use HTTPS
Webhook URLs must use HTTPS to ensure secure transmission of delivery status data.
### 2. Verify Webhook Secret
Check the `X-OTPIQ-Webhook-Secret` header to verify the webhook authenticity:
```javascript theme={null}
const receivedSecret = req.headers["x-otpiq-webhook-secret"];
const expectedSecret = "your_webhook_secret_123";
if (receivedSecret !== expectedSecret) {
return res.status(401).send("Unauthorized");
}
```
### 3. Respond Quickly
Your webhook endpoint should respond with a 2xx status code within 10 seconds to acknowledge receipt.
### 4. Handle Duplicates
Implement idempotency using the `smsId` to handle potential duplicate webhooks:
```javascript theme={null}
const processedMessages = new Set();
if (processedMessages.has(payload.smsId)) {
return res.status(200).send("Already processed");
}
processedMessages.add(payload.smsId);
// Process the webhook...
```
### 5. Log Everything
Log all webhook requests for debugging and monitoring purposes.
## Common Issues & Solutions
### Webhook Not Received
**Possible Causes:**
* Webhook URL is not accessible from the internet
* Server is not responding within 10 seconds
* HTTPS certificate issues
**Solutions:**
* Verify webhook URL accessibility
* Check server logs for errors
* Ensure HTTPS is properly configured
### Authentication Failures
**Possible Causes:**
* Webhook secret mismatch
* Missing or incorrect header validation
**Solutions:**
* Verify webhook secret matches exactly
* Check `X-OTPIQ-Webhook-Secret` header name and value
### Timeout Errors
**Possible Causes:**
* Webhook endpoint taking too long to respond
* Heavy processing blocking the response
**Solutions:**
* Respond quickly (within 10 seconds)
* Implement async processing for heavy operations
## Testing Webhooks
### Using webhook.site
For testing purposes, you can use [webhook.site](https://webhook.site) to inspect webhook payloads:
1. Go to [webhook.site](https://webhook.site)
2. Copy the generated URL
3. Use it as your `webhookUrl` in API requests
4. Send a test SMS
5. Monitor the webhook payloads in real-time
### Sample Webhook Handler
Here's a basic Node.js webhook handler example:
```javascript theme={null}
const express = require("express");
const app = express();
app.use(express.json());
app.post("/webhooks/sms-status", (req, res) => {
const webhookSecret = req.headers["x-otpiq-webhook-secret"];
const payload = req.body;
// Verify webhook secret
if (webhookSecret !== "your_webhook_secret_123") {
return res.status(401).send("Unauthorized");
}
// Process the webhook
console.log("SMS Status Update:", {
smsId: payload.smsId,
status: payload.status,
channel: payload.channel,
isFinal: payload.isFinal,
});
// Update your database or trigger other actions
if (payload.status === "delivered") {
// Handle successful delivery
} else if (payload.status === "failed") {
// Handle failed delivery
console.log("Failure reason:", payload.reason);
}
// Respond quickly
res.status(200).send("OK");
});
app.listen(3000, () => {
console.log("Webhook server running on port 3000");
});
```
## Rate Limits
* **Webhook Delivery**: Up to 10 retries with exponential backoff
* **Timeout**: 10 seconds per webhook request
* **Queue Size**: Unlimited webhook queue
If your webhook endpoint consistently fails or times out, OTPIQ may
temporarily disable webhook delivery to prevent system overload.
# Get Started with Otpiq
Source: https://docs.otpiq.com/index
Welcome to OTPIQ documentation - your comprehensive API reference and help center
## Welcome to OTPIQ Documentation
Welcome to the OTPIQ documentation! This comprehensive resource serves as both your **API reference** and **help center**, providing everything you need to integrate and work with Otpiq's services.
Get up and running with OTPIQ in minutes. Follow our step-by-step guide to
make your first API call.
Complete API documentation with interactive examples and endpoint details.
Find answers to common questions and troubleshooting guides.
Access your OTPIQ dashboard to manage your account and view analytics.
## What's Inside
This documentation provides:
* **Complete API Reference**: Detailed documentation for all OTPIQ endpoints with interactive examples
* **Help Center**: Comprehensive guides, troubleshooting tips, and best practices
* **Code Examples**: Ready-to-use code snippets in multiple programming languages
* **Integration Guides**: Step-by-step tutorials for popular platforms and frameworks
## Need Help?
Can't find what you're looking for? Reach out to our support team at
[info@otpiq.com](mailto:info@otpiq.com)
Join our developer community on
[GitHub](https://github.com/orgs/otpiq/discussions) for discussions and
contributions.
Stay updated with the latest features and announcements on [X
(Twitter)](https://x.com/otp_iq).
***
**Ready to get started?** Check out our [Quickstart guide](/quickstart) to
make your first API call in under 5 minutes.
# Quickstart
Source: https://docs.otpiq.com/quickstart
Get started with OTPIQ API in minutes
## Get started with OTPIQ API
Follow these simple steps to start using OTPIQ's API and integrate it into your application.
### Step 1: Get your API key
1. Go to the [OTPIQ Dashboard](https://app.otpiq.com)
2. Sign in to your
account or create a new one
3. Navigate to your project settings
1. In your project settings, find the "API Keys" section
2. Click "Generate
New Key"
3. Copy your API key and keep it secure
**Important**: Store your API key securely and never expose it in
client-side code or public repositories.
### Step 2: Explore the API reference
Now that you have your API key, head over to our [API
Reference](/api-reference/introduction) to: - Learn about available endpoints
* See interactive examples - Understand authentication requirements - Explore
request/response formats
### Step 3: Make your first API call
1. Use the examples in our API reference 2. Include your API key in the
Authorization header 3. Start with simple endpoints to test your integration
All API requests require your API key in the Authorization header:
`Authorization: Bearer YOUR_API_KEY`
## Next steps
Now that you have your API key and understand the basics, explore these resources:
Complete API documentation with all available endpoints and examples.
See practical examples for common API operations.
Monitor your API usage and manage your account.
**Need help?** Contact our support team at
[info@otpiq.com](mailto:info@otpiq.com) or join our [GitHub
community](https://github.com/otpiq).
# OTPIQ Anti-Fraud System
Source: https://docs.otpiq.com/useful-articles/anti-fraud-system
Protect your project from spam and abuse using OTPIQ's advanced phone number and IP address rate limiting features.
OTPIQ provides a robust fraud protection system that monitors both phone numbers and IP addresses to cut down on abuse, save your credit balance, and protect end-users from being spammed.
To get started, you first need to enable rate limiting for your project.
## Enabling Rate Limiting
Log in to the OTPIQ Dashboard, go to your **Settings**, and select the **Limits** tab.
Set how many OTPs a single phone number can receive within a specific time frame (e.g., maximum of 5 OTPs per 10 minutes).
Set how many OTPs a single IP address can send across all phone numbers within a specific time frame.
***
## Types of Protection
OTPIQ defends your project on two distinct levels:
This works as a recipient-level anti-fraud measure. It prevents anyone from sending an abnormal number of messages to the exact same phone number.
Prevents your project's balance from being drained by repeated requests.
Ensures the recipient does not get spammed with endless OTP messages.
Attackers often try to bypass phone number limits by cycling through random phone numbers. IP address rate limiting stops this by restricting how many requests a single IP can make, regardless of the phone numbers being targeted.
**Integration Requirement:**
To make IP address limiting work, you must include the requester's IP address in your API request body.
Pass it inside an `anti_fraud` object using the `requester_ip` property:
```json theme={null}
{
"phone_number": "+1234567890",
"anti_fraud": {
"requester_ip": "192.168.1.1"
}
}
```
***
## The Fraud Protection Dashboard
Once rate limiting is enabled, the **Fraud Protection** page in your dashboard provides a comprehensive view of blocked activity.
### Overview Metrics & Charts
* **Total Blocked:** See exactly how many IP addresses and phone numbers are currently "jailed".
* **Historical Data:** View cards showing how many targets were rate-limited today and over the last 30 days.
* **Visual Charts:** Track total blocked requests per day and see a breakdown of the countries where blocked IPs originate.
### Managing Blocked Activity
The dashboard includes detailed tables for both blocked IP addresses and blocked phone numbers. These tables show the target, location, how many requests they sent before being jailed, and how many blocked requests they've attempted since.
When dealing with a blocked IP address, you have three action choices:
1. **Remove jail time:** Allows the IP to start sending OTPs again immediately.
2. **Add to allow list:** Whitelists the IP so it will never be rate-limited again (ideal for your own dev servers).
3. **Add to permanent ban list:** Completely blocks the IP from ever sending OTPs to your project.
***
## Deep Dive: Inspect & Risk Assessment
When you are unsure what action to take on a blocked IP, you can use the **Inspect** button to gather more context.
View the IP's country, city, ISP, and a map of its approximate location. It also identifies whether the IP is a standard residential address or hiding behind a proxy/VPN.
See exactly how many times this specific IP has been jailed in your project to determine if it's an honest mistake or active abuse.
### AI-Powered Risk Assessment
Reviewing data manually can be overwhelming during a high-traffic attack. OTPIQ does the heavy lifting by combining your project's data with external threat signals.
Clicking the **Risk Assessment** button generates a report that includes:
* An overall **Threat Level**
* A clear **Verdict** on what action you should take
This allows you to confidently decide whether to let the jail time expire naturally, remove it, or permanently block the attacker.
***
## IP Allow & Ban Lists
Under the **IP List** tab, you can manually manage your IP access controls independently of the automated rate limiting:
* **Allowed IP Addresses:** Add IPs that should bypass all rate limits (e.g., your backend servers or trusted partners).
* **Banned IP Addresses:** Manually add IPs that should be permanently blocked from interacting with your project.
# Do I need a Sender ID?
Source: https://docs.otpiq.com/useful-articles/do-i-need-sender-id
Understand whether you need to register a Sender ID for SMS, WhatsApp, and Telegram, including requirements and registration times.
When sending messages through OTPIQ, you might wonder if you need a dedicated Sender ID (your brand name) for your communications. The requirements and options vary depending on the messaging channel you are using.
For SMS, registering a Sender ID is **optional**. When registered, you can send messages using your own brand name instead of a generic number.
The price for SMS is determined by the carrier and can change over time. Please check the [OTPIQ main website](https://otpiq.com) for the most up-to-date pricing.
### Registration requirements
Registering an SMS Sender ID requires a **valid Iraqi company license**.
The Sender ID can differ from your official company name, but you must provide proof of connection between the brand and the company. Acceptable proof includes:
* Trademark registration
* Having the company name explicitly stated on the brand's website or app
### Estimated registration times
1 to 3 days
1 to 3 weeks
By default, all WhatsApp messages are sent under the official OTPIQ account.
### Using the default OTPIQ account
* **No setup required**: You can start using it directly
* **Unlimited messaging**: You don't have to worry about hitting tier limits
* You cannot see user responses to your messages
* Your brand name is not shown (OTPIQ's name is displayed)
* You can only send OTP (One-Time Password) messages
### Using your own WhatsApp account
You can use your own WhatsApp account to send messages with your brand name.
You must have a valid, verified **Meta Business Account** at [business.facebook.com](https://business.facebook.com).
This is different from having a verified Facebook page (blue badge). You specifically need a verified Meta Business Account.
Once verified, connect your WhatsApp account in the [OTPIQ Dashboard](https://app.otpiq.com/connect-whatsapp-account).
The pricing remains exactly the same whether you use the default OTPIQ account or your own connected WhatsApp account.
For Telegram, there is currently **no way** to register a custom brand name or Sender ID.
# How Dev Keys Work
Source: https://docs.otpiq.com/useful-articles/how-dev-key-works
Learn how to use Development Keys to safely test your integration without sending messages to real users.
When building and testing your integration with OTPIQ, you want to ensure that OTP messages and notifications are not accidentally sent to real users' phone numbers. To solve this, OTPIQ provides **Development Keys (Dev Keys)**.
A Dev Key acts as a safe alternative to your production API key during the development phase.
## What is a Dev Key?
A Dev Key is a special type of API key tied to a specific "development phone number" that you define.
When you use a Dev Key in your API requests, **OTPIQ will intercept the request and send the message exclusively to your defined development phone number**, completely ignoring the phone number provided in the API request payload.
This means you can safely test your application using real user data or dummy data without the risk of spamming actual users. All test messages will conveniently route to your own device.
## How to set up and use a Dev Key
Setting up a Dev Key is quick and can be done directly from your dashboard.
Log in to the [OTPIQ Dashboard](https://app.otpiq.com) and go to your **Project Settings**.
Locate the Development Keys section and create a new key. During creation, you will be prompted to define a **development phone number**.
In your development environment or local codebase, replace your production API key with the newly generated Dev Key.
Send API requests exactly as you would in production.
No matter what `phone_number` you pass in the API request body, the message will always be delivered to the development phone number you defined in Step 2.
Remember to swap your Dev Key back to your production API key when deploying your application to your live environment!
# SMS character limits
Source: https://docs.otpiq.com/useful-articles/sms-character-support
Learn how the characters you use affect SMS message length, encoding types, and billing for your otpiq messaging traffic.
When you send an SMS message through otpiq, the characters you use and the length of your message determine how many actual SMS parts are sent over the network. If you use parameterization for personalized messages, remember that the length might vary based on recipient-specific data.
The otpiq API automatically detects the required encoding based on the characters in your message body, ensuring seamless delivery in any language.
## Basic character set (GSM 7-bit)
You can send up to 160 characters in a single SMS message if all characters belong to the standard GSM 7-bit alphabet. This is the most common encoding for standard text.
### Supported GSM 7-bit characters
The standard alphabet includes basic Latin characters, digits, and common punctuation:
* **Letters:** `A-Z`, `a-z`
* **Digits:** `0-9`
* **Punctuation and symbols:** `@ £ $ ¥ è é ù ì ò Ç Ø ø Å å Δ _ Φ Γ Λ Ω Π Ψ Σ Θ Ξ Æ æ ß É SP ! " # ¤ % & ' ( ) * + , - . / : ; < = > ? ¡ Ä Ö Ñ Ü § ¿ ä ö ñ ü à`
* **Control characters:** Line Feed (`LF`) and Carriage Return (`CR`)
When formatting your message payload in JSON, provide the Line Feed character as `\n`.
### Extended character set
Certain characters are supported under the GSM 7-bit encoding but count as **two characters** in your SMS message instead of one:
```text theme={null}
| ^ € { } [ ] ~ \
```
Be mindful when using extended characters. Because they consume two character spaces, they quickly eat into your 160-character limit and may push your text into a multi-part message.
## Other languages and symbols (Unicode)
If your message requires characters outside the GSM 7-bit alphabet (such as emojis, or characters from languages like Arabic, Chinese, or Cyrillic), otpiq automatically uses **16-bit Unicode (UCS-2)** encoding.
When your message uses UCS-2 encoding, each character takes 2 bytes. This reduces the maximum length of a single SMS message from 160 characters down to **70 characters**.
## Long multi-part messages
You can send a message body with up to 2000 characters. Since standard SMS limits are 160 (GSM) or 70 (Unicode) characters, longer texts are split into multiple message parts. These parts are reassembled on the recipient's device, so it appears as one continuous message to your customers.
Each message part requires a header for reassembly, which slightly reduces the character limit per part in long messages.
### Multi-part limits for 7-bit encoding
Each part in a multi-part 7-bit encoded message has a maximum length of **153 characters**.
| Message Length (characters) | Number of SMS Parts |
| --------------------------- | ------------------- |
| 1–160 | 1 |
| 161–306 | 2 |
| 307–459 | 3 |
| 460–612 | 4 |
| 613–765 | 5 |
| 766–918 | 6 |
| 919–1061 | 7 |
| 1062–1214 | 8 |
This pattern continues up to 14 parts for a 2000-character message.
### Multi-part limits for Unicode encoding
Each part in a multi-part Unicode encoded message has a maximum length of **67 characters**.
| Message Length (characters) | Number of SMS Parts |
| --------------------------- | ------------------- |
| 1–70 | 1 |
| 71–134 | 2 |
| 135–201 | 3 |
| 202–268 | 4 |
| 269–335 | 5 |
| 336–402 | 6 |
| 403–469 | 7 |
| 470–538 | 8 |
This pattern continues up to 30 parts for a 2000-character message.
Messages exceeding 2000 characters will be rejected by the otpiq API and return a 400 error. Ensure you track message lengths, especially when injecting dynamic variables.
# WhatsApp Business Calling and call permission
Source: https://docs.otpiq.com/useful-articles/whatsapp-call-permission
Learn how WhatsApp Business Calling works in OTPIQ, what you need to place or receive calls, and how call permission requests work.
WhatsApp Business Calling lets you talk to customers over voice inside WhatsApp — from the OTPIQ inbox — without sharing a personal phone number. This guide explains how calling works, what you need before you start, and why **call permission** matters for outbound calls.
Calling is available on WhatsApp Business accounts connected to OTPIQ. If you have not connected an account yet, follow [How to connect WhatsApp API](/whatsapp-business-api/how-to-connect-whatsapp-api).
## What is WhatsApp Business Calling?
WhatsApp Business Calling is Meta’s voice feature for the WhatsApp Business Platform. In OTPIQ, agents answer and place calls from the **WhatsApp inbox** in the browser using WebRTC (your microphone and speakers).
There are two call directions:
| Direction | Who starts the call | Permission required? | Typical use |
| ---------------------- | ------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------- |
| **User-initiated** | The customer calls your business number | No extra permission from you | Support, sales follow-up after the customer taps Call |
| **Business-initiated** | Your team calls the customer from the inbox | Yes — the customer must grant call permission first | Proactive support, order help, scheduled callbacks |
Incoming (user-initiated) calls ring in the OTPIQ inbox when your WhatsApp number is connected and calling is enabled. Outbound (business-initiated) calls always need prior customer consent.
## What you need
Before you can use WhatsApp calling in OTPIQ, confirm the following:
A WhatsApp Business account and phone number linked to your project via [embedded signup](/whatsapp-business-api/how-to-connect-whatsapp-api).
Voice calling must be enabled on the business phone number. OTPIQ configures this for connected accounts; contact support if the call button never appears.
Use a modern desktop browser and allow microphone access. Outbound calls cannot start without a working mic.
Business-initiated calls are billed per minute. Prepaid projects need enough balance to cover at least one minute before dialing.
For **business-initiated** calls you also need:
1. An **approved** call permission request template
2. The customer’s **Accept** response (temporary or permanent)
3. Permission that is still valid when you dial (temporary grants expire)
***
## Call permission explained
WhatsApp does not let businesses cold-call customers. For outbound WhatsApp calls, the recipient must explicitly allow your business to call them.
### How customers grant permission
1. You send a **call permission request** template from OTPIQ.
2. WhatsApp shows the customer **Accept** and **Decline** actions automatically (you do not add buttons yourself).
3. If they Accept, they can choose:
* **Temporary** — usually valid for about **7 days**
* **Permanent** — until they revoke it in WhatsApp settings
4. The reply appears in the inbox conversation (granted, declined, and expiry when temporary).
5. After Accept, use the **Call** button in that chat to place the call.
If you try to call before permission is granted — or after temporary permission expires — OTPIQ blocks the call and prompts you to send a permission request first.
### Call permission request templates
A call permission request is a special WhatsApp template type. Meta rules for this template:
| Rule | Detail |
| ------------------- | -------------------------------------------------------------------------------- |
| **Category** | Must be **Utility** (fixed by Meta) |
| **Body** | Required — explain why you want to call |
| **Header / footer** | Optional text only (no media header) |
| **Buttons** | Not allowed — WhatsApp adds Accept / Decline for you |
| **Variables** | You can use `{{1}}`, `{{2}}`, … in header or body (for example order ID or name) |
| **Approval** | Must be **Approved** by Meta before you can send it |
Example body text:
```text theme={null}
We would like to call you to help support your request. May we call you?
```
You can customize the wording for your brand, as long as it clearly asks for permission to call.
***
## Set up business-initiated calling
Complete [embedded signup](/whatsapp-business-api/how-to-connect-whatsapp-api) so your WABA and phone number appear in the project.
In the dashboard, open your WhatsApp templates and create a new template with type **Call permission**.
* Category is locked to **Utility**
* Write a clear body (and optional header/footer)
* Submit for Meta review
Wait until the template status is **Approved** before sending it to customers.
Open the conversation in the WhatsApp inbox and send the approved call permission template.
If you press **Call** without permission, OTPIQ opens a dialog where you can select an approved template and send it immediately.
When the contact taps **Allow**, the conversation shows that call permission was granted (temporary with an expiry, or permanent).
Click **Call** in the chat. Allow microphone access when the browser asks, then wait for the customer to answer.
***
## Receiving customer calls
When a customer calls your WhatsApp business number:
1. An incoming call notification appears in the OTPIQ inbox.
2. An agent accepts or rejects the call.
3. On accept, the browser sets up the voice session (microphone required).
4. Either side can end the call; the conversation timeline records the call event.
User-initiated calls do **not** require a call permission template. Permission is only for when **your business** starts the call.
***
## Pricing and billing
Business-initiated WhatsApp calls are charged **per minute**, based on the destination market of the number you call.
* Billing starts when the call is answered and connected.
* Duration is rounded up to whole minutes (a short answered call still bills at least one minute).
* Prepaid projects must have enough credit for at least the first minute before dialing; if balance runs out during a call, the call may be ended automatically.
* Rates depend on the callee’s country/market — check the rate shown in the inbox when you start an outbound call.
Incoming (user-initiated) call handling in the inbox does not use the same outbound per-minute charge model. Focus outbound budget planning on business-initiated calls.
***
## Common issues
The contact has not granted permission yet, or temporary permission expired. Send an approved call permission request template and wait for **Accept**, then call again.
Create a **Call permission** template under WhatsApp templates, submit it, and wait for Meta to mark it **Approved**. Pending or rejected templates cannot be sent for calling consent.
Allow microphone access in the browser. Use a stable network. Corporate firewalls that block WebRTC/STUN can prevent call setup — try another network or contact OTPIQ support if calls never connect.
Top up your project balance. Outbound calls need enough prepaid credit for at least one minute at the destination rate before dialing.
You cannot place a business-initiated call until they Accept a new request. Send another permission template only when it is appropriate (for example after they ask for a callback).
***
## Related guides
Link your WhatsApp Business account to OTPIQ with embedded signup.
Understand quality ratings and daily messaging tiers for your number.
Fix currency, payment method, and WABA errors during signup.
Overview of templates, categories, and how the platform works.
If you need help enabling calling on a number or reviewing a stuck permission template, contact [info@otpiq.com](mailto:info@otpiq.com) or WhatsApp [9647501580221](https://wa.me/9647501580221).
# Troubleshoot WhatsApp connection errors
Source: https://docs.otpiq.com/useful-articles/whatsapp-connection-errors
Understand common error messages when connecting your WhatsApp Business account to OTPIQ and how to fix them.
When you connect a WhatsApp Business account to OTPIQ, Meta may return an error during embedded signup or when you link an existing account. This guide explains what each message means and what to do next.
Accounts created through OTPIQ's [embedded signup](/whatsapp-business-api/how-to-connect-whatsapp-api) are configured with the correct currency automatically. Most issues appear when you reuse a WhatsApp account that was created elsewhere or linked to another provider.
## Quick reference
| Error | Typical cause | Fix |
| ---------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Wrong currency | WABA billing currency is not AUD | Change currency to AUD in Meta, or create a new account via embedded signup |
| Payment method / currency mismatch | Card or billing already set on the WABA with a different currency | Remove payment methods in Meta, or create a new account |
| WABA not found | Rare Meta-side issue | Contact OTPIQ support |
***
## Wrong currency
### What you see
Meta reports that the WhatsApp account has the **wrong currency** (or a currency mismatch during connection).
### What it means
Every WhatsApp Business account connected to OTPIQ must use **AUD (Australian dollars)** as its billing currency. OTPIQ routes WhatsApp billing through Meta's infrastructure in a way that requires this setting.
If you created the account through OTPIQ's embedded signup, AUD is applied for you. If the account was created earlier, linked to another BSP (Business Solution Provider), or set up manually in Meta, the currency may still be something else.
### Check your currency
Go to [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account) in Meta Business Suite.
Choose the WhatsApp Business account you are trying to connect to OTPIQ.
Find the **currency** field and verify it is set to **AUD**.
### How to fix it
Update the currency to **AUD** in [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account), then try connecting again from the [OTPIQ Dashboard](https://app.otpiq.com/connect-whatsapp-account).
Sometimes Meta does not always allow changing currency on an existing WhatsApp Business account. In that case, create a **new** WhatsApp account using OTPIQ's [embedded signup](/whatsapp-business-api/how-to-connect-whatsapp-api) so AUD is set automatically.
***
## Payment method already set (currency mismatch)
### What you see
```text theme={null}
The WhatsApp Business Account passed in already has a payment method, and the inputted currency is different from the one already set for this WABA. Please try again with different inputs.
```
### What it means
This WhatsApp Business account (**WABA**) already has billing configured in Meta with a payment method and a currency that does not match what OTPIQ needs (AUD). That usually happens when:
* The account is **still connected** to another third-party WhatsApp provider, or was connected before and billing was left in place
* Someone **added a credit card** to the WABA directly in the Meta Business dashboard
Meta will not let OTPIQ attach its billing setup on top of conflicting payment settings.
### How to fix it
Go to [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account).
Choose the account you want to connect to OTPIQ.
Remove any **payment methods** linked to that WhatsApp Business account.
Return to the [OTPIQ Dashboard](https://app.otpiq.com/connect-whatsapp-account) and run embedded signup again.
If the account is still tied to another provider, disconnect it there first when possible, then remove payment methods in Meta before reconnecting to OTPIQ.
If you cannot clear billing or the account must stay with another provider, create a **new** WhatsApp Business account through OTPIQ's [embedded signup](/whatsapp-business-api/how-to-connect-whatsapp-api) instead of reusing the existing WABA.
***
## WABA not found
### What you see
```text theme={null}
WABA not found
```
(The message includes a numeric or alphanumeric WhatsApp Business Account ID.)
### What it means
Meta could not find the WhatsApp Business account ID used during the connection flow. This is **uncommon** and usually points to a temporary or internal issue on Meta's side, or a mismatch between the account Meta returns during signup and what OTPIQ expects to link.
This is not something you can reliably fix from the Meta dashboard alone.
### How to fix it
Wait a few minutes, then try [connecting again](https://app.otpiq.com/connect-whatsapp-account). Clear your browser cache or use a private window if signup behaves oddly.
If the error persists, email [info@otpiq.com](mailto:info@otpiq.com) with:
* The full error message (including the WABA ID)
* The email on your Meta Business account
* When the error occurred (date and time)
Our team can check the connection on our side and work with Meta if the WABA ID is invalid or out of sync.
***
## Still stuck?
If none of the steps above resolve your issue, contact [info@otpiq.com](mailto:info@otpiq.com) or message us on WhatsApp at [9647501580221](https://wa.me/9647501580221). Include a screenshot of the error and whether you are using a new embedded signup account or an existing WABA from another provider.
# Connect WhatsApp Account
Source: https://docs.otpiq.com/whatsapp-business-api/how-to-connect-whatsapp-api
Step-by-step guide to integrating your WhatsApp Business API account with Otpiq
Follow these steps to connect your WhatsApp Business API and start sending messages through Otpiq.
## Prerequisites
Before starting the integration, ensure you have:
* A Facebook account with admin access to your Meta Business Account.
* A phone number ready for verification.
The phone number **cannot** be currently registered on the regular WhatsApp or WhatsApp Business mobile apps. If it is, you must delete the account from the app first.
## Step 1: Connect via Otpiq Dashboard
Log in to [app.otpiq.com](https://app.otpiq.com) and go to **WhatsApp** → **Account**.
Click **"Connect WhatsApp Account"** to launch the embedded signup process.
Follow the prompts to sign in to Facebook, connect your Meta Business Account, and grant Otpiq the necessary permissions. Once finished, your account will be automatically linked.
## Step 2: Create WhatsApp Templates
To send business-initiated messages, you need approved templates.
Navigate to the **Templates** section in your Otpiq dashboard and click **Create New Template**.
Select a category (Marketing, Utility, or Authentication), set the language, and fill in the content (header, body, buttons).
Submit the template to WhatsApp. Approval usually takes less than 24 hours.
## Step 3: Send Messages
Once your templates are approved, you can send messages using the Otpiq dashboard or API.
**Test easily**: Go to **Dashboard → Messaging → Send SMS** to build and test your WhatsApp template messages without writing any code.
Here is an example of sending a template via the API:
```json theme={null}
{
"phoneNumber": "9647501580221",
"smsType": "whatsapp-template",
"provider": "whatsapp",
"templateName": "auth_temp_new_no_exp",
"whatsappAccountId": "68c46fecc504cdcec8fb3ef2",
"whatsappPhoneId": "68c46ff3c504cdcec8fb3f5e",
"templateParameters": {
"body": {
"1": "123456"
}
}
}
```
Check the [API Reference](/api-reference/introduction) for complete endpoint details.
## Troubleshooting
| Issue | Solution |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Connection Failed** | Verify you have admin permissions for both the Meta Business Account and the WhatsApp Business API. |
| **Facebook Signup Issues** | Clear your browser cache or disable ad-blockers, then try again. |
| **Currency or payment errors** | See [Troubleshoot WhatsApp connection errors](/useful-articles/whatsapp-connection-errors) for wrong currency, payment method conflicts, and WABA not found. |
| **Template Rejected** | Ensure you aren't using promotional language in a "Utility" template and that all variable parameters are correct. |
***
**Need Help?** Contact our support team at [info@otpiq.com](mailto:info@otpiq.com).
# What is WhatsApp Business API?
Source: https://docs.otpiq.com/whatsapp-business-api/what-is-whatsapp-business-api
Learn about WhatsApp Business API, its features, and how it works
## What is WhatsApp Business API?
WhatsApp Business API is an enterprise-level solution that enables businesses to communicate with customers at scale. Unlike the standard WhatsApp Business app, the API allows:
* **Automated messaging** for notifications, alerts, and updates
* **Two-way conversations** with customers
* **Integration** with CRM systems and business tools
* **Multiple agent support** for customer service teams
* **Verified business profiles** with green checkmarks
WhatsApp Business API is ideal for businesses sending high volumes of messages
or requiring advanced automation and integration capabilities.
## What are WhatsApp Business API Accounts Used For?
WhatsApp Business API accounts serve various business communication needs:
### Customer Notifications
* Order confirmations and updates
* Appointment reminders
* Delivery notifications
* Payment receipts
### Authentication & Security
* One-Time Passwords (OTPs)
* Two-factor authentication (2FA)
* Account verification codes
* Login alerts
### Customer Support
* Automated responses to FAQs
* Support ticket updates
* Real-time assistance
* Post-purchase follow-ups
### Marketing & Engagement
* Product announcements
* Promotional offers (with user consent)
* Cart abandonment reminders
* Customer feedback requests
## Understanding WhatsApp Message Templates
Message templates are pre-approved message formats required by WhatsApp for business-initiated conversations. Templates must be submitted and approved before you can start messaging customers.
### Why Templates?
WhatsApp requires templates to:
* Prevent spam and maintain quality
* Ensure user privacy
* Provide consistent user experience
* Comply with messaging policies
### Template Components
A WhatsApp template consists of:
| Component | Description | Required |
| ----------- | ------------------------------------- | ------------ |
| **Header** | Text, image, video, or document | Optional |
| **Body** | Main message content with variables | **Required** |
| **Footer** | Additional info (e.g., disclaimer) | Optional |
| **Buttons** | Call-to-action or quick reply buttons | Optional |
## Types of WhatsApp Templates & Pricing
WhatsApp offers three distinct template categories, each serving different purposes and having different pricing structures.
### 1. Authentication Templates
**Purpose:** Used for account verification, OTP codes, and security-related messages.
**Pricing:** **25 IQD** per message
**Important Restrictions:**
Authentication templates have a **fixed, static format that cannot be
customized**. WhatsApp enforces this to maintain security standards and ensure
consistency across all authentication messages.
**Format Structure:**
Authentication templates have a **fixed, preset structure** that includes:
* **Fixed preset text**: `{{1}} is your verification code.`
* **Optional security disclaimer**: `For your security, do not share this code.`
* **Optional expiration warning**: `This code expires in {{2}} minutes.`
* **Button options**: One-tap autofill, copy code button, or no button (zero-tap)
**Example - Authentication Template:**
```
{{1}} is your verification code.
For your security, do not share this code.
This code expires in {{2}} minutes.
Button: [Copy Code]
```
**Variables allowed:**
* `{{1}}` - Your verification code (required)
* `{{2}}` - Expiration time in minutes (optional, 1-90 minutes)
**Button Types:**
* **One-tap autofill**: Automatically fills the code in your app (Android only)
* **Copy code**: Copies the code to clipboard
* **Zero-tap**: No button, user manually enters the code
**Use Cases:**
* One-Time Passwords (OTP)
* Login verification codes
* Account activation codes
* Password reset codes
Authentication templates are the most affordable option, making them ideal for
high-volume verification needs like OTPs and login codes.
### 2. Utility Templates
**Purpose:** Used for transactional updates, notifications, and important account-related information.
**Pricing:** **25 IQD** per message
**Customization:** **Fully customizable** - You have complete control over content, format, and design.
**Example - Order Confirmation Template:**
```
Header: 🎉 Order Confirmed!
Body: Hi {{1}},
Your order #{{2}} has been confirmed and will be delivered by {{3}}.
Track your order: {{4}}
Total Amount: ${{5}}
Thank you for shopping with us!
Footer: Questions? Reply to this message.
Buttons:
[Track Order] [View Invoice]
```
**Variables:** Up to 10 variables allowed
**Parameter Formats:**
* **Positional**: `{{1}}`, `{{2}}`, `{{3}}` (ordered by appearance)
* **Named**: `{{customer_name}}`, `{{order_number}}` (can appear in any order)
**Use Cases:**
* Order confirmations and updates
* Shipping notifications
* Appointment reminders
* Payment receipts
* Booking confirmations
* Account alerts
### 3. Marketing Templates
**Purpose:** Used for promotional content, offers, and marketing campaigns.
**Pricing:** **60 IQD** per message
**Customization:** **Fully customizable** with additional requirements for opt-out options.
**Requirements:**
Marketing templates **must include** an opt-out mechanism and are only allowed
if you have explicit user consent to send promotional messages. Users must
have opted in to receive marketing communications.
**Important Restrictions:**
Starting April 1, 2025, WhatsApp will temporarily pause delivery of marketing
template messages to users with United States phone numbers. This affects
global businesses sending to US users.
**Example - Promotional Offer Template:**
```
Header: [Image: Promotional Banner]
Body: Hi {{1}}! 🎁
Exclusive offer just for you!
Get {{2}}% OFF on your next purchase of {{3}}.
Use code: {{4}}
Valid until: {{5}}
Shop now and save big!
Footer: Reply STOP to unsubscribe from promotional messages.
Buttons:
[Shop Now] [View Catalog]
```
**Variables:** Up to 10 variables allowed
**Parameter Formats:**
* **Positional**: `{{1}}`, `{{2}}`, `{{3}}` (ordered by appearance)
* **Named**: `{{customer_name}}`, `{{discount_percent}}` (can appear in any order)
**Use Cases:**
* Product launches
* Special offers and discounts
* Seasonal promotions
* Abandoned cart reminders
* Customer re-engagement campaigns
* Event invitations
## Template Pricing Comparison
| Template Type | Cost Per Message | Customizable | Variables | Best For | Approval Time |
| ------------------ | ---------------- | ------------ | --------- | ---------------------- | ------------- |
| **Authentication** | **25 IQD** | ❌ No | 1-2 | OTPs, Security codes | 1-5 minutes |
| **Utility** | **25 IQD** | ✅ Yes | Up to 10 | Transactional messages | 1-24 hours |
| **Marketing** | **60 IQD** | ✅ Yes | Up to 10 | Promotional campaigns | 1-48 hours |
**Cost-effective tip:** Use Authentication or Utility templates (25 IQD each)
for transactional messages. Reserve Marketing templates (60 IQD) only for
promotional campaigns to optimize your messaging costs.
## Template Creation Guidelines
### Template Names
* **Maximum length**: 512 characters
* **Format**: Lowercase alphanumeric characters and underscores only
* **Uniqueness**: Names are not unique - you can have multiple templates with the same name in different languages
### Template Limits
* **Creation limit**: Maximum 100 templates per WhatsApp Business Account per hour
* **Total templates**:
* Unverified business portfolio: 250 templates per account
* Verified business portfolio: Up to 6,000 templates per account
### Language Requirements
* Each template must be created for each language you plan to use
* Template strings and variables are not automatically translated
* You must provide content in the appropriate language for each template
### Template Status
Templates must have `APPROVED` status before they can be sent. Status options include:
* **In-Review**: Under review (up to 24 hours)
* **Approved**: Ready to send
* **Rejected**: Violates policies or guidelines
* **Paused**: Temporarily disabled due to poor quality feedback
* **Disabled**: Permanently disabled due to recurring issues
## Choosing the Right Template Type
**Use Authentication templates when:**
* Sending OTPs or verification codes
* User security is the priority
* You want zero messaging costs
* You can work with the standard format
**Use Utility templates when:**
* Sending transactional updates
* Providing order/booking information
* Sharing important account notifications
* You need custom branding and messaging
**Use Marketing templates when:**
* Running promotional campaigns
* Announcing new products or offers
* Re-engaging customers
* You have explicit consent for marketing
Templates must be approved by WhatsApp before use. Approval time varies:
Authentication templates are usually approved within minutes, while Utility
and Marketing templates may take up to 48 hours.
## Ready to Get Started?
Now that you understand WhatsApp Business API and its capabilities, you're ready to connect your account to Otpiq.
Follow our step-by-step guide to integrate your WhatsApp Business API with
Otpiq
Explore our comprehensive API documentation for sending messages
## Next Steps
* [Explore the API Reference](/api-reference/introduction)
* [Learn about Webhook Integration](/essentials/how-webhook-works)
* [Start Sending Messages](/quickstart)
# Message Limits and Scaling
Source: https://docs.otpiq.com/whatsapp-business-api/whatsapp-messaging-limits
A comprehensive guide to WhatsApp Business API messaging limits, scaling paths, and how to increase your daily message capacity
# Understanding WhatsApp Business API Message Limits
WhatsApp Business API message limits determine how many unique customers you can message each day. Understanding these limits is crucial for planning your messaging strategy and scaling your business communications.
## What Are Message Limits?
Message limits are the **maximum number of unique WhatsApp user phone numbers** your business can deliver messages to, outside of customer service windows, within a moving 24-hour period.
**Key Point**: Limits are calculated at the **business portfolio level** and
shared by all phone numbers within that portfolio. This means if you have
multiple WhatsApp Business numbers, they all share the same daily limit.
## Starting Limits
When you first create a WhatsApp Business API account, you start with:
* **New Business Portfolios**: 250 messages per day
* **New Phone Numbers**: Share the portfolio's limit (not individual 250 limit)
## Limit Tiers
Your messaging limit can be increased through these tiers:
| Tier | Daily Message Limit | How to Achieve |
| ---------------- | ------------------- | --------------------------------- |
| **Tier 250** | 250 messages | Starting limit for new portfolios |
| **Tier 2,000** | 2,000 messages | Complete scaling path |
| **Tier 10,000** | 10,000 messages | Automatic scaling |
| **Tier 100,000** | 100,000 messages | Automatic scaling |
| **Unlimited** | No limit | Automatic scaling |
## How to Increase Your Limit to 2,000
To move from 250 to 2,000 messages per day, you need to complete **one** of these scaling paths:
### Option 1: Verify Your Business
Complete business verification through Meta Business Manager. This is the fastest way to increase your limit.
### Option 2: Send High-Quality Messages
Send 2,000 delivered messages outside of customer service windows to unique WhatsApp users in a 30-day period using templates with high quality ratings.
**Quality Matters**: Your message quality rating significantly impacts your
ability to scale. Focus on sending relevant, valuable messages to maintain
high quality scores.
## Automatic Scaling (2,000+ Messages)
Once you reach 2,000 messages, WhatsApp will automatically increase your limit if you meet these criteria:
* **High-Quality Messages**: You're sending high-quality messages across all phone numbers and templates
* **Utilization**: In the last 7 days, you've used at least half of your current messaging limit
**Fast Scaling**: Automatic limit increases happen within **6 hours** when you
meet the criteria.
## Portfolio-Based Limits
WhatsApp Business API uses a portfolio-based limit system where all phone numbers within a business portfolio share the same daily messaging limit.
### How Portfolio-Based Limits Work
* **Shared Capacity**: All WhatsApp Business phone numbers in your portfolio share the same daily limit
* **Immediate Access**: New phone numbers automatically get the portfolio's current limit
* **Unlimited Numbers**: You can add as many phone numbers as needed without affecting your limit
* **Centralized Management**: One limit to manage across all your business numbers
## Checking Your Current Limit
1. Go to [app.otpiq.com](https://app.otpiq.com) and log in to your account
2. Navigate to **WhatsApp** → **Account**
3. View your current messaging limit and scaling information
## Message Quality and Scaling
Your ability to scale depends heavily on message quality. WhatsApp evaluates:
* **Relevance**: Messages should be relevant to recipients
* **Engagement**: Recipients should engage positively with your messages
* **Compliance**: Follow WhatsApp's commerce and business policies
* **Template Quality**: Use well-designed, approved templates
**Quality Rating**: Maintain "Medium" or "High" quality ratings across all
your templates to ensure smooth scaling.
## Customer Service Windows
Important: Message limits only apply to messages sent **outside** of customer service windows. Within 24 hours of a customer messaging you, you can send unlimited messages to that customer.
**Customer Service Window**: 24-hour period after a customer initiates contact
where you can send unlimited messages without counting against your daily
limit.
## Best Practices for Scaling
### 1. Start with High-Quality Templates
* Use clear, relevant messaging
* Avoid promotional language in utility templates
* Include proper opt-out mechanisms for marketing
### 2. Monitor Your Usage
* Track your daily message consumption
* Aim to use at least 50% of your limit for automatic scaling
* Monitor quality ratings regularly
### 3. Plan Your Scaling Strategy
* Begin with business verification for fastest scaling
* Focus on utility and authentication templates (lower cost, higher approval rates)
* Build up to 2,000 messages before expanding to marketing
### 4. Maintain Quality Standards
* Respond promptly to customer messages
* Avoid spam-like behavior
* Follow WhatsApp's best practices
## Common Scaling Issues
| Issue | Solution |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| **Stuck at 250** | Complete business verification or send 2,000 high-quality messages |
| **Quality Rating Low** | Improve message relevance and engagement |
| **Not Utilizing Limit** | Increase message volume while maintaining quality |
| **Template Rejections** | [Review WhatsApp policies](https://business.whatsapp.com/policy) and improve template content |
## Throughput Limits
Beyond daily message limits, WhatsApp also has throughput limits (messages per second):
* **Standard**: 80 messages per second
* **High Throughput**: 1,000 messages per second (requires unlimited daily limit)
To qualify for high throughput:
* Portfolio must have unlimited messaging limit
* Phone number must message 100K+ unique users in 24 hours
* Maintain Medium or High quality rating
## Next Steps
Ready to start scaling your WhatsApp messaging? Here's what to do:
1. **Connect Your Account**: Follow our [WhatsApp Business API connection guide](/whatsapp-business-api/how-to-connect-whatsapp-api)
2. **Create Quality Templates**: Design templates that provide value to your customers
3. **Monitor Performance**: Track your message quality and usage
4. **Scale Gradually**: Build up to higher limits through consistent, high-quality messaging
Learn how to connect your WhatsApp Business API to Otpiq
Explore our comprehensive API documentation
***
*Need help with your WhatsApp Business API setup? Contact our support team at [info@otpiq.com](mailto:info@otpiq.com) or check our [documentation](/quickstart) for more guides.*
# WhatsApp Inbound Webhooks
Source: https://docs.otpiq.com/whatsapp-business-api/whatsapp-webhook
Receive real-time notifications to your server when inbound messages hit your WhatsApp Business number
We've added **WhatsApp inbound webhooks** so you can get real-time notifications when someone messages your WhatsApp Business number. Instead of polling or checking the dashboard, your backend gets a POST request as soon as a message arrives.
Trigger bots or auto-responders from your own infrastructure.
Push conversations into your ticketing or CRM system in real time.
Record or analyze inbound traffic in your data warehouse.
Run any logic (notifications, queues, integrations) when a message is received.
Configuration is **per phone number**. You can choose which numbers send events to your endpoint and keep the rest internal to Otpiq (e.g., for the built-in inbox only).
## Security and Verification
For each webhook you configure, we generate a unique **webhook secret**. This token looks like `otpiq_live_sk` followed by 64 hex characters.
**Never expose your secret** in client-side code or public repositories. Store it securely in environment variables or a secrets manager.
### Verifying the Webhook Signature
We sign every webhook request using HMAC-SHA256 so you can verify that it came from Otpiq and hasn't been tampered with.
Read the raw request body as UTF-8 (before parsing it as JSON).
Read the `X-OTPIQ-Webhook-Timestamp` and `X-OTPIQ-Webhook-Signature` headers.
Concatenate the timestamp and the raw body with a dot: `timestamp + "." + raw_body`.
Compute the HMAC-SHA256 of the concatenated string using your **webhook secret** as the key.
Compare your computed hex value with the `sha256=` value from the signature header. Use a constant-time comparison to avoid timing attacks.
If the signatures match, process the request. If they don't, reject it with a `401 Unauthorized` or `403 Forbidden` status.
### Webhook Headers
We include several headers with every request to provide context and support idempotency.
| Header | Description |
| --------------------------- | ----------------------------------------------------------- |
| `Content-Type` | `application/json` |
| `X-OTPIQ-Webhook-Event` | The event type (e.g., `whatsapp.inbound_message.received`). |
| `X-OTPIQ-Webhook-Event-Id` | Unique ID for this event. Use this to deduplicate requests. |
| `X-OTPIQ-Webhook-Timestamp` | The timestamp used in the signature. |
| `X-OTPIQ-Webhook-Attempt` | The delivery attempt number (1, 2, 3, etc.). |
| `X-OTPIQ-Webhook-Signature` | `sha256=` format signature for verification. |
## Delivery and Retries
A delivery is considered successful when your endpoint returns a **2xx status code** within our timeout window. Redirects are not followed.
### Retry Strategy
If your endpoint returns a non-2xx status, times out, or fails to connect, we use the following retry strategy:
We make up to 3 attempts in quick succession:
* **1st attempt**: Immediate (or after a 1s delay in the first burst)
* **2nd attempt**: 10 seconds after the first attempt
* **3rd attempt**: 15 seconds after the second attempt
If all 3 immediate attempts fail, the event is marked as `queued_retry`.
* We schedule the next try in **about 1 hour**.
* A background job processes these retries hourly.
* If it fails again, it's rescheduled for another hour.
We continue hourly retries for **up to 2 days**. After that, the event is discarded and no further delivery attempts are made.
### Log Retention
You can view **webhook event logs** for each phone number in the dashboard. These logs show the status, attempt count, and the last error or response received.
* Logs are **retained for 15 days** before being automatically deleted.
* During this 15-day window, you can inspect attempts and **manually retry** failed events from the UI.