WhatsApp Business API Documentation

https://docs.otpiq.com
Admin
Comprehensive documentation for the WhatsApp Business API, including API references, quickstarts,...
Tokens:29,674
Snippets:212
Trust Score:5.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### WhatsApp Marketing Template Example: Promotional Offer

Source: https://docs.otpiq.com/whatsapp-business-api/what-is-whatsapp-business-api

An example of a Marketing template for a promotional offer, featuring a header image, body with discount details, and buttons. This template also uses positional variables and requires an opt-out footer.

```plaintext
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]
```

--------------------------------

### WhatsApp Utility Template Example: Order Confirmation

Source: https://docs.otpiq.com/whatsapp-business-api/what-is-whatsapp-business-api

An example of a Utility template for order confirmation, including header, body, footer, and buttons. This template uses positional variables.

```plaintext
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]
```

--------------------------------

### OpenAPI Specification for GET /info

Source: https://docs.otpiq.com/api-reference/endpoint/get

This snippet shows the OpenAPI 3.1.1 specification for the GET /info endpoint, which retrieves project details.

```yaml
openapi: 3.1.1
info:
  title: OTPIQ SMS API
  description: >-
    Enterprise-grade SMS and messaging API for sending verification codes,
    custom messages, and managing sender IDs. Supports multiple providers
    including SMS, WhatsApp, and Telegram with intelligent fallback routing.


    ## Features


    * **Multi-Provider Support**: Send messages via SMS, WhatsApp, or Telegram

    * **Smart Fallback Routes**: Automatic provider switching for maximum
    delivery success

    * **Verification Codes**: Automated OTP delivery with customizable codes

    * **Custom Messages**: Send personalized messages with custom sender IDs

    * **Rate Limiting**: Built-in protection against abuse

    * **Spending Controls**: Configurable spending thresholds and credit
    management

    * **Real-time Tracking**: Monitor message delivery status

    * **Sender ID Management**: Register and manage custom sender IDs

    * **Webhook Notifications**: Real-time delivery status updates via webhooks


    ## Provider Options


    OTPIQ now offers 6 provider options including smart fallback routes:

    - **`whatsapp-sms`**: Try WhatsApp first, fallback to SMS

    - **`telegram-sms`**: Try Telegram first, fallback to SMS

    - **`whatsapp-telegram-sms`**: Try WhatsApp → Telegram → SMS (maximum
    delivery success)

    - **`sms`**: SMS only

    - **`whatsapp`**: WhatsApp only

    - **`telegram`**: Telegram only


    ## Authentication


    All API requests require authentication using your project API key. Include
    it in the Authorization header:

    ```

    Authorization: Bearer sk_live_your_api_key_here

    ```


    ## Webhooks


    OTPIQ provides real-time delivery status notifications via webhooks. See the
    Webhooks section for detailed documentation and examples.


    ## Support


    * **Documentation**: [https://docs.otpiq.com](https://docs.otpiq.com)

    * **Support Email**: info@otpiq.com
  version: 1.0.0
  contact:
    name: OTPIQ Support
    url: https://otpiq.com
    email: info@otpiq.com
  license:
    name: Commercial
    url: https://otpiq.com/terms
servers:
  - url: https://api.otpiq.com/api
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: API key authentication and project information
  - name: SMS
    description: >-
      Send SMS messages, verification codes, and track delivery with multiple
      provider options and fallback routing
  - name: Sender IDs
    description: Manage custom sender IDs for your messages
  - name: Webhooks
    description: Real-time delivery status notifications via webhooks
  - name: Delivery Reports
    description: Generate and list CSV delivery reports for SMS/messages in a date range
  - name: Pricing
    description: Retrieve international SMS pricing information
  - name: WhatsApp
    description: >-
      List WhatsApp businesses, accounts, phone numbers, and message templates
      connected to a project
externalDocs:
  description: OTPIQ Documentation
  url: https://docs.otpiq.com
paths:
  /info:
    get:
      tags:
        - Authentication
      summary: Get project information
      description: >-
        Retrieve information about the authenticated project including remaining
        credits and project details.
      operationId: getProjectInfo
      responses:
        '200':
          description: >-
            Project information retrieved successfully. Response body includes:
            projectName (string), credit (number).
          content:
            application/json:
              schema:
                type: object
                required:
                  - projectName
                  - credit
                properties:
                  projectName:
                    type: string
                    description: Name of the project
                    examples:
                      - My SMS Project
                  credit:
                    type: number
                    description: Remaining credit balance in IQD
                    minimum: 0
                    examples:
                      - 15000
              examples:
                success:
                  summary: Successful response
                  value:
                    projectName: My SMS Project
                    credit: 15000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: Unauthorized error message
                    examples:
                      - Unauthorized, please use your project api key
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object

```

--------------------------------

### Example Authentication Message Template

Source: https://docs.otpiq.com/whatsapp-business-api/what-is-whatsapp-business-api

This is an example of an authentication message template. It includes a verification code, a security disclaimer, an expiration warning, and a 'Copy Code' button. Variables {{1}} and {{2}} are placeholders for the verification code and expiration time, respectively.

```plaintext
{{1}} is your verification code.

For your security, do not share this code.

This code expires in {{2}} minutes.

Button: [Copy Code]
```

--------------------------------

### Example API Key Authentication

Source: https://docs.otpiq.com/api-reference/endpoint/get

Use your project API key in the Authorization header for all API requests.

```http
Authorization: Bearer sk_live_your_api_key_here
```

--------------------------------

### Successful Project Info Response

Source: https://docs.otpiq.com/api-reference/endpoint/get

Example of a successful response when retrieving project information, including project name and remaining credits.

```json
{
  "projectName": "My SMS Project",
  "credit": 15000
}
```

--------------------------------

### Webhook Example: Delivered Status

Source: https://docs.otpiq.com/essentials/how-webhook-works

An example of a webhook payload received when an SMS message status changes to 'delivered'.

```APIDOC
## Webhook Example: Delivered Status

### Description
This is an example of a webhook payload received when an SMS message status changes to 'delivered'.

### Response Example
```json
{
  "smsId": "sms_1234567890abcdef",
  "deliveryReportType": "all",
  "isFinal": true,
  "channel": "sms",
  "status": "delivered",
  "senderId": "OTPIQ"
}
```
```

--------------------------------

### Get Project Info

Source: https://docs.otpiq.com/llms.txt

Retrieve information about the authenticated project including remaining credits and project details.

```APIDOC
## GET /api-reference/endpoint/get

### Description
Retrieve information about the authenticated project including remaining credits and project details.

### Method
GET

### Endpoint
/api-reference/endpoint/get
```

--------------------------------

### Webhook Example: Sent Status

Source: https://docs.otpiq.com/essentials/how-webhook-works

An example of a webhook payload received when an SMS message status changes to 'sent'.

```APIDOC
## Webhook Example: Sent Status

### Description
This is an example of a webhook payload received when an SMS message status changes to 'sent'.

### Response Example
```json
{
  "smsId": "sms_1234567890abcdef",
  "deliveryReportType": "all",
  "isFinal": false,
  "channel": "sms",
  "status": "sent",
  "senderId": "OTPIQ"
}
```
```

--------------------------------

### SMS Request with Webhook Configuration

Source: https://docs.otpiq.com/essentials/how-webhook-works

This example demonstrates how to include the `deliveryReport` object in your SMS request to configure webhooks for receiving delivery status updates.

```APIDOC
## SMS Request with Webhook Configuration

### Description
This example demonstrates how to include the `deliveryReport` object in your SMS request to configure webhooks for receiving delivery status updates.

### Request Body
```json
{
  "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

- **webhookUrl** (string, required) - The HTTPS URL where delivery status updates will be sent. Must use HTTPS protocol. Example: `https://your-app.com/webhooks/sms-status`
- **deliveryReportType** (string, optional, default: "all") - Controls when webhooks are triggered. Can be `"all"` (for all status updates) or `"final"` (only for delivered or failed status).
- **webhookSecret** (string, optional) - 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`
```

--------------------------------

### Get Project Information

Source: https://docs.otpiq.com/api-reference/endpoint/get

Retrieve information about the authenticated project, including its name and remaining credit balance. This endpoint is useful for monitoring your account status.

```APIDOC
## GET /info

### Description
Retrieve information about the authenticated project including remaining credits and project details.

### Method
GET

### Endpoint
/info

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **projectName** (string) - Name of the project
- **credit** (number) - Remaining credit balance in IQD

#### Response Example
```json
{
  "projectName": "My SMS Project",
  "credit": 15000
}
```

#### Error Responses
- **401 Unauthorized**: Unauthorized, please use your project api key
- **500 Internal Server Error**: Internal Server Error
```

--------------------------------

### OpenAPI Error Message Example

Source: https://docs.otpiq.com/api-reference/endpoint/get

Defines the structure for an internal server error message within the OpenAPI specification.

```yaml
required:
  - message
properties:
  message:
    type: string
    description: Internal server error message
    examples:
      - Internal server error
```

--------------------------------

### Get Project WhatsApp Resources

Source: https://docs.otpiq.com/api-reference/whatsapp/resources

Retrieves comprehensive details about WhatsApp resources linked to a specific project. This includes project identifiers, summary statistics like business and account counts, and a detailed list of connected Meta businesses, their WhatsApp accounts, and associated phone numbers.

```APIDOC
## GET /websites/otpiq/whatsapp/resources

### Description
Retrieves detailed information about WhatsApp resources associated with a project, including summary statistics and connected businesses.

### Method
GET

### Endpoint
/websites/otpiq/whatsapp/resources

### Parameters
#### Query Parameters
- **projectId** (string) - Required - The unique identifier for the project.

### Response
#### Success Response (200)
- **slug** (string) - Project slug.
- **name** (string) - Project display name.
- **summary** (object) - Summary statistics for WhatsApp resources.
  - **businessCount** (integer) - Number of connected Meta businesses.
  - **accountCount** (integer) - Number of WhatsApp Business Accounts (WABAs).
  - **phoneNumberCount** (integer) - Number of phone numbers across all WABAs.
  - **templateCount** (integer) - Number of message templates across all WABAs.
- **businesses** (array) - Connected Meta businesses. Empty array if none are linked.
  - **id** (string) - Unique identifier for the business.
  - **businessId** (string) - Meta business ID.
  - **name** (string) - Name of the business.
  - **whatsappAccounts** (array) - WhatsApp Business Accounts (WABAs) linked to the business.
    - **id** (string) - Unique identifier for the WABA.
    - **whatsappBusinessId** (string) - WABA ID.
    - **name** (string) - Name of the WABA.
    - **accountReviewStatus** (string) - Status of the WABA account review (e.g., APPROVED).
    - **businessVerificationStatus** (string) - Verification status of the business (e.g., verified).
    - **banState** (string) - Ban status of the WABA.
    - **banDate** (string) - Date when the WABA was banned.
    - **violationType** (string) - Type of violation that led to a ban.
    - **phoneNumbers** (array) - Phone numbers associated with the WABA.
      - **id** (string) - Unique identifier for the phone number.
      - **phoneNumberId** (string) - Meta phone number ID.
      - **displayPhoneNumber** (string) - The phone number displayed to users.
      - **phoneNumber** (string) - The actual phone number.
      - **verifiedName** (string) - The verified name associated with the phone number.
      - **qualityRating** (string) - Quality rating of the phone number (e.g., GREEN).
      - **messagingLimit** (string) - Messaging limit tier for the phone number (e.g., TIER_1K).
      - **status** (string) - Connection status of the phone number (e.g., CONNECTED).
      - **codeVerificationStatus** (string) - Verification status of the phone number code (e.g., VERIFIED).
      - **isOfficialBusinessAccount** (boolean) - Indicates if it's an Official Business Account.

#### Response Example
{
  "slug": "example-project",
  "name": "Example Project",
  "summary": {
    "businessCount": 1,
    "accountCount": 2,
    "phoneNumberCount": 3,
    "templateCount": 10
  },
  "businesses": [
    {
      "id": "biz_123",
      "businessId": "meta_biz_456",
      "name": "Example Business",
      "whatsappAccounts": [
        {
          "id": "waba_789",
          "whatsappBusinessId": "waba_id_abc",
          "name": "Example WABA",
          "accountReviewStatus": "APPROVED",
          "businessVerificationStatus": "verified",
          "banState": "ACTIVE",
          "banDate": null,
          "violationType": null,
          "phoneNumbers": [
            {
              "id": "pn_def",
              "phoneNumberId": "meta_pn_ghi",
              "displayPhoneNumber": "+1 555-123-4567",
              "phoneNumber": "5551234567",
              "verifiedName": "Example Business Inc.",
              "qualityRating": "GREEN",
              "messagingLimit": "TIER_1K",
              "status": "CONNECTED",
              "codeVerificationStatus": "VERIFIED",
              "isOfficialBusinessAccount": true
            }
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Get WhatsApp Resources

Source: https://docs.otpiq.com/api-reference/whatsapp/resources

Retrieves information about the WhatsApp account associated with the project, including its messaging limit, connection status, verification status, and a list of message templates.

```APIDOC
## GET /v1/whatsapp/resources

### Description
Retrieves information about the WhatsApp account associated with the project, including its messaging limit, connection status, verification status, and a list of message templates.

### Method
GET

### Endpoint
/v1/whatsapp/resources

### Parameters
#### Query Parameters
- **includeTemplateComponents** (boolean) - Optional - If true, includes template components in the response.

### Response
#### Success Response (200)
- **messagingLimit** (string) - The messaging tier limit for the WhatsApp account.
- **status** (string) - The connection status of the WhatsApp account.
- **codeVerificationStatus** (string) - The verification status of the WhatsApp code.
- **isOfficialBusinessAccount** (boolean) - Indicates if it's an official business account.
- **nameStatus** (string) - The approval status of the business name.
- **createdAt** (string) - The timestamp when the WhatsApp resource was created.
- **templates** (array) - A list of message templates associated with the account.
  - **id** (string) - The unique identifier for the template.
  - **name** (string) - The name of the template.
  - **category** (string) - The category of the template (e.g., AUTHENTICATION).
  - **parameter_format** (string) - The format for parameters in the template (e.g., POSITIONAL).
  - **language** (string) - The language of the template.
  - **messageSendTtlSeconds** (integer) - The time-to-live in seconds for sending messages with this template.
  - **reason** (string) - The reason for the template's status.
  - **status** (string) - The approval status of the template.
  - **isWhatsappFlow** (boolean) - Indicates if the template is part of a WhatsApp flow.
  - **createdAt** (string) - The timestamp when the template was created.

#### Error Response (400)
- **error** (string) - Description of the error if the `includeTemplateComponents` value is invalid.

#### Error Response (401)
- **message** (string) - Unauthorized error message.

#### Error Response (403)
- **message** (string) - Error message indicating the request IP is not allowed when IP whitelist is enabled.

#### Error Response (500)
- **success** (boolean) - Always false.
- **message** (string) - Message indicating a server error while fetching resources.
```

--------------------------------

### Get Sender IDs

Source: https://docs.otpiq.com/llms.txt

Retrieve all sender IDs associated with the authenticated project.

```APIDOC
## GET /api-reference/sender-id/get

### Description
Retrieve all sender IDs associated with the authenticated project.

### Method
GET

### Endpoint
/api-reference/sender-id/get
```

--------------------------------

### Unauthorized Error Response

Source: https://docs.otpiq.com/api-reference/endpoint/get

Example of an unauthorized error response when the API key is missing or invalid.

```json
{
  "message": "Unauthorized, please use your project api key"
}
```

--------------------------------

### Get Sender IDs

Source: https://docs.otpiq.com/api-reference/sender-id/get

Retrieve all sender IDs associated with the authenticated project. This endpoint returns a list of sender IDs along with their status and pricing information.

```yaml
openapi: 3.1.1
info:
  title: OTPIQ SMS API
  description: >-
    Enterprise-grade SMS and messaging API for sending verification codes,
    custom messages, and managing sender IDs. Supports multiple providers
    including SMS, WhatsApp, and Telegram with intelligent fallback routing.


  ## Features


  * **Multi-Provider Support**: Send messages via SMS, WhatsApp, or Telegram

  * **Smart Fallback Routes**: Automatic provider switching for maximum
    delivery success

  * **Verification Codes**: Automated OTP delivery with customizable codes

  * **Custom Messages**: Send personalized messages with custom sender IDs

  * **Rate Limiting**: Built-in protection against abuse

  * **Spending Controls**: Configurable spending thresholds and credit
    management

  * **Real-time Tracking**: Monitor message delivery status

  * **Sender ID Management**: Register and manage custom sender IDs

  * **Webhook Notifications**: Real-time delivery status updates via webhooks


  ## Provider Options


  OTPIQ now offers 6 provider options including smart fallback routes:

  - **`whatsapp-sms`**: Try WhatsApp first, fallback to SMS

  - **`telegram-sms`**: Try Telegram first, fallback to SMS

  - **`whatsapp-telegram-sms`**: Try WhatsApp → Telegram → SMS (maximum
    delivery success)

  - **`sms`**: SMS only

  - **`whatsapp`**: WhatsApp only

  - **`telegram`**: Telegram only


  ## Authentication


  All API requests require authentication using your project API key. Include
  it in the Authorization header:

  ```

  Authorization: Bearer sk_live_your_api_key_here

  ```


  ## Webhooks


  OTPIQ provides real-time delivery status notifications via webhooks. See the
  Webhooks section for detailed documentation and examples.


  ## Support


  * **Documentation**: [https://docs.otpiq.com](https://docs.otpiq.com)

  * **Support Email**: info@otpiq.com
  version: 1.0.0
  contact:
    name: OTPIQ Support
    url: https://otpiq.com
    email: info@otpiq.com
  license:
    name: Commercial
    url: https://otpiq.com/terms
servers:
  - url: https://api.otpiq.com/api
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: API key authentication and project information
  - name: SMS
    description: >-
      Send SMS messages, verification codes, and track delivery with multiple
      provider options and fallback routing
  - name: Sender IDs
    description: Manage custom sender IDs for your messages
  - name: Webhooks
    description: Real-time delivery status notifications via webhooks
  - name: Delivery Reports
    description: Generate and list CSV delivery reports for SMS/messages in a date range
  - name: Pricing
    description: Retrieve international SMS pricing information
  - name: WhatsApp
    description: >-
      List WhatsApp businesses, accounts, phone numbers, and message templates
      connected to a project
externalDocs:
  description: OTPIQ Documentation
  url: https://docs.otpiq.com
paths:
  /sender-ids:
    get:
      tags:
        - Sender IDs
      summary: Get sender IDs
      description: Retrieve all sender IDs associated with the authenticated project.
      operationId: getSenderIds
      responses:
        '200':
          description: >-
            Sender IDs retrieved successfully. Response body includes: success
            (boolean), data (array of SenderId).
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    description: Whether the request was successful
                    examples:
                      - true
                  data:
                    type: array
                    description: Array of sender IDs
                    items:
                      type: object
                      required:
                        - _id
                        - senderId
                        - status
                        - pricePerSms
                      properties:
                        _id:
                          type: string
                          description: Unique identifier for the sender ID
                          examples:
                            - 507f1f77bcf86cd799439011
                        senderId:
                          type: string
                          description: The sender ID name
                          maxLength: 11
                          examples:
                            - OTPIQ
                        status:
                          type: string
                          enum:
                            - pending
                            - accepted
                            - rejected

```

--------------------------------

### Send WhatsApp Template Message via API

Source: https://docs.otpiq.com/whatsapp-business-api/how-to-connect-whatsapp-api

Example JSON payload for sending a WhatsApp template message using the Otpiq API. Ensure the template name and parameters match your approved WhatsApp templates.

```json
{
  "phoneNumber": "9647501580221",
  "smsType": "whatsapp-template",
  "provider": "whatsapp",
  "templateName": "auth_temp_new_no_exp",
  "whatsappAccountId": "68c46fecc504cdcec8fb3ef2",
  "whatsappPhoneId": "68c46ff3c504cdcec8fb3f5e",
  "templateParameters": {
    "body": {
      "1": "123456"
    }
  }
}
```

--------------------------------

### OpenAPI Specification for International SMS Pricing

Source: https://docs.otpiq.com/api-reference/messaging/international-sms-pricing

This OpenAPI 3.1.1 specification defines the GET /international-sms-pricing endpoint, including parameters for pagination and country filtering, and the structure of the successful response.

```yaml
openapi: 3.1.1
info:
  title: OTPIQ SMS API
  description: >-
    Enterprise-grade SMS and messaging API for sending verification codes,
    custom messages, and managing sender IDs. Supports multiple providers
    including SMS, WhatsApp, and Telegram with intelligent fallback routing.


  ## Features


  * **Multi-Provider Support**: Send messages via SMS, WhatsApp, or Telegram

  * **Smart Fallback Routes**: Automatic provider switching for maximum
    delivery success

  * **Verification Codes**: Automated OTP delivery with customizable codes

  * **Custom Messages**: Send personalized messages with custom sender IDs

  * **Rate Limiting**: Built-in protection against abuse

  * **Spending Controls**: Configurable spending thresholds and credit
    management

  * **Real-time Tracking**: Monitor message delivery status

  * **Sender ID Management**: Register and manage custom sender IDs

  * **Webhook Notifications**: Real-time delivery status updates via webhooks


  ## Provider Options


  OTPIQ now offers 6 provider options including smart fallback routes:

  - **`whatsapp-sms`**: Try WhatsApp first, fallback to SMS

  - **`telegram-sms`**: Try Telegram first, fallback to SMS

  - **`whatsapp-telegram-sms`**: Try WhatsApp → Telegram → SMS (maximum
    delivery success)

  - **`sms`**: SMS only

  - **`whatsapp`**: WhatsApp only

  - **`telegram`**: Telegram only


  ## Authentication


  All API requests require authentication using your project API key. Include
  it in the Authorization header:

  ```

  Authorization: Bearer sk_live_your_api_key_here

  ```


  ## Webhooks


  OTPIQ provides real-time delivery status notifications via webhooks. See the
  Webhooks section for detailed documentation and examples.


  ## Support


  * **Documentation**: [https://docs.otpiq.com](https://docs.otpiq.com)

  * **Support Email**: info@otpiq.com
  version: 1.0.0
  contact:
    name: OTPIQ Support
    url: https://otpiq.com
    email: info@otpiq.com
  license:
    name: Commercial
    url: https://otpiq.com/terms
servers:
  - url: https://api.otpiq.com/api
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: API key authentication and project information
  - name: SMS
    description: >-
      Send SMS messages, verification codes, and track delivery with multiple
      provider options and fallback routing
  - name: Sender IDs
    description: Manage custom sender IDs for your messages
  - name: Webhooks
    description: Real-time delivery status notifications via webhooks
  - name: Delivery Reports
    description: Generate and list CSV delivery reports for SMS/messages in a date range
  - name: Pricing
    description: Retrieve international SMS pricing information
  - name: WhatsApp
    description: >-
      List WhatsApp businesses, accounts, phone numbers, and message templates
      connected to a project
externalDocs:
  description: OTPIQ Documentation
  url: https://docs.otpiq.com
paths:
  /international-sms-pricing:
    get:
      tags:
        - Pricing
      summary: List international SMS pricing
      description: >-
        Paginated international SMS price rows. Each item's `price` is the
        billed amount in IQD per one SMS segment (one 140-character segment)
      operationId: listInternationalSmsPricing
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000000
            default: 1
          description: 'Page index. Range: 1 to 1,000,000.'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
          description: 'Page size. Range: 1 to 500.'
        - name: countryIso
          in: query
          required: false
          schema:
            type: string
            pattern: '^[A-Za-z]{2}$'
            examples:
              - IQ
          description: >-
            Optional two-letter ISO country code (for example, IQ). Matching is
            case-insensitive.
      responses:
        '200':
          description: International SMS pricing list retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - currency
                  - page
                  - limit
                  - total
                  - pages
                properties:
                  currency:
                    type: string
                    examples:
                      - IQD
                  page:
                    type: integer
                    minimum: 1
                    examples:
                      - 1
                  limit:

```

--------------------------------

### Track SMS

Source: https://docs.otpiq.com/llms.txt

Get the delivery status of a specific SMS message.

```APIDOC
## GET /api-reference/messaging/track

### Description
Get the delivery status of a specific SMS message.

### Method
GET

### Endpoint
/api-reference/messaging/track
```

--------------------------------

### Get SMS Status

Source: https://docs.otpiq.com/api-reference/messaging/track

Retrieve the status of a specific SMS message using its ID.

```APIDOC
## GET /websites/otpiq/track/{smsId}

### Description
Retrieves the status and delivery details of a specific SMS message.

### Method
GET

### Endpoint
/websites/otpiq/track/{smsId}

### Parameters
#### Path Parameters
- **smsId** (string) - Required - The unique identifier of the SMS message.

### Response
#### Success Response (200)
- **smsId** (string) - The unique identifier of the SMS message.
- **phoneNumber** (string) - The recipient's phone number.
- **status** (string) - The current status of the SMS (e.g., 'sent').
- **cost** (number) - The cost of sending the SMS in IQD. Minimum 0.
- **isFinalStatus** (boolean) - Whether the SMS has reached a final state.
- **lastChannel** (string) - The last channel attempted or used for sending ('sms', 'whatsapp', 'telegram').
- **channelFlow** (array) - Sequence of channels and their attempt statuses.
  - **channel** (string) - Messaging channel ('sms', 'whatsapp', 'telegram').
  - **tried** (boolean) - Whether this channel was attempted.
  - **success** (boolean | null) - Whether this channel succeeded.
  - **error** (string | null) - Error message if the attempt failed.
  - **refunded** (boolean | null) - Whether the cost for this channel was refunded.

#### Response Example
```json
{
  "smsId": "sms-1234567890abcdef123456",
  "phoneNumber": "964750123456",
  "status": "sent",
  "cost": 200,
  "isFinalStatus": false,
  "lastChannel": "whatsapp",
  "channelFlow": [
    {
      "channel": "whatsapp",
      "tried": true,
      "success": true
    },
    {
      "channel": "sms",
      "tried": false
    }
  ]
}
```

#### Error Response (401)
- **message** (string) - Unauthorized error message.

#### Error Response (404)
- **message** (string) - Not found error message.

#### Error Response (500)
- **message** (string) - Internal server error message.

### Security
- **bearerAuth**: Project API key (`sk_live…` or `sk_dev…`). Send it as `Authorization: Bearer <api_key>`.
```

--------------------------------

### WhatsApp Account and Template Details

Source: https://docs.otpiq.com/api-reference/whatsapp/resources

This snippet shows the structure of a successful response when fetching WhatsApp account and template resources. It includes details like messaging limits, account status, and template configurations.

```json
{
  "messagingLimit": "TIER_1K",
  "status": "CONNECTED",
  "codeVerificationStatus": "VERIFIED",
  "isOfficialBusinessAccount": false,
  "nameStatus": "APPROVED",
  "createdAt": "2026-01-15T10:00:00.000Z",
  "templates": [
    {
      "id": "65e4e4e4e4e4e4e4e4e4e4e4",
      "name": "otp_verification",
      "category": "AUTHENTICATION",
      "parameter_format": "POSITIONAL",
      "language": "en",
      "messageSendTtlSeconds": 600,
      "reason": "",
      "status": "APPROVED",
      "isWhatsappFlow": false,
      "createdAt": "2026-01-20T08:30:00.000Z"
    }
  ],
  "createdAt": "2026-01-10T12:00:00.000Z"
}
```

--------------------------------

### List Delivery Reports

Source: https://docs.otpiq.com/llms.txt

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.

```APIDOC
## GET /api-reference/reports/list

### Description
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.

### Method
GET

### Endpoint
/api-reference/reports/list
```

--------------------------------

### List WhatsApp Resources

Source: https://docs.otpiq.com/llms.txt

Discover connected WhatsApp businesses, WABAs, phone numbers, and message templates for your project.

```APIDOC
## GET /api-reference/whatsapp/resources

### Description
Discover connected WhatsApp businesses, WABAs, phone numbers, and message templates for your project.

### Method
GET

### Endpoint
/api-reference/whatsapp/resources
```

--------------------------------

### Project Resource Structure

Source: https://docs.otpiq.com/api-reference/whatsapp/resources

This snippet details the structure of a Project resource, including its ID, slug, name, and associated summary data like business, account, and template counts.

```APIDOC
## Project Resource

### Description
Represents a project within the system, containing configurations and data related to WhatsApp integration.

### Properties
- **id** (string) - The unique identifier for the project.
- **slug** (string) - A URL-friendly identifier for the project.
- **name** (string) - The display name of the project.
- **summary** (object) - An object containing aggregated counts for related resources.
  - **businessCount** (integer) - The total number of businesses associated with the project.
  - **accountCount** (integer) - The total number of WhatsApp accounts associated with the project.
  - **phoneNumberCount** (integer) - The total number of phone numbers associated with the project.
  - **templateCount** (integer) - The total number of message templates associated with the project.
- **businesses** (array) - A list of businesses associated with the project.
  - **id** (string) - The unique identifier for the business.
  - **businessId** (string) - The external business ID.
  - **name** (string) - The name of the business.
  - **whatsappAccounts** (array) - A list of WhatsApp accounts associated with the business.
    - **id** (string) - The unique identifier for the WhatsApp account.
    - **whatsappBusinessId** (string) - The external WhatsApp Business Account ID.
    - **name** (string) - The name of the WhatsApp account.
    - **accountReviewStatus** (string) - The review status of the WhatsApp account (e.g., APPROVED).
    - **businessVerificationStatus** (string) - The verification status of the business.
    - **banState** (string) - The ban state of the account.
    - **banDate** (string) - The date the account was banned.
    - **violationType** (string) - The type of violation that led to a ban.
    - **phoneNumbers** (array) - A list of phone numbers associated with the WhatsApp account.
      - **id** (string) - The unique identifier for the phone number.
      - **phoneNumberId** (string) - The external phone number ID.
      - **displayPhoneNumber** (string) - The phone number formatted for display.
      - **phoneNumber** (string) - The raw phone number.
      - **verifiedName** (string) - The verified name associated with the phone number.
      - **qualityRating** (string) - The quality rating of the phone number (e.g., GREEN).
- **createdAt** (string) - The timestamp when the project was created.
```

--------------------------------

### SMS Request with Custom Sender ID

Source: https://docs.otpiq.com/essentials/how-webhook-works

Example of an SMS request that includes a custom sender ID and webhook configuration.

```json
{
  "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"
  }
}
```

--------------------------------

### Get Sender ID Status

Source: https://docs.otpiq.com/api-reference/sender-id/get

Retrieves the approval status of a sender ID and its associated pricing per SMS for various carriers.

```APIDOC
## GET /sender-id

### Description
Retrieves the approval status of a sender ID and its associated pricing per SMS for various carriers.

### Method
GET

### Endpoint
/sender-id

### Parameters
#### Query Parameters
- **senderId** (string) - Required - The sender ID to check.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - An array of sender ID objects.
  - **_id** (string) - The unique identifier for the sender ID entry.
  - **senderId** (string) - The sender ID.
  - **status** (string) - The approval status of the sender ID (e.g., 'accepted').
  - **pricePerSms** (object) - Pricing per SMS for different carriers.
    - **korekTelecom** (number) - Price for Korek Telecom.
    - **asiaCell** (number) - Price for AsiaCell.
    - **zainIraq** (number) - Price for Zain Iraq.
    - **others** (number) - Price for other carriers.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "senderId": "OTPIQ",
      "status": "accepted",
      "pricePerSms": {
        "korekTelecom": 80,
        "asiaCell": 80,
        "zainIraq": 80,
        "others": 100
      }
    }
  ]
}
```

#### Error Response (401)
- **message** (string) - Unauthorized error message.

#### Error Response (500)
- **message** (string) - Internal server error message.
```

--------------------------------

### List WhatsApp Resources

Source: https://docs.otpiq.com/api-reference/whatsapp/resources

Retrieves all WhatsApp resources linked to the project, including connected Meta businesses, WhatsApp Business Accounts (WABAs), phone numbers, and message templates. The project is resolved from the API key.

```yaml
openapi: 3.1.1
info:
  title: OTPIQ SMS API
  description: >-
    Enterprise-grade SMS and messaging API for sending verification codes,
    custom messages, and managing sender IDs. Supports multiple providers
    including SMS, WhatsApp, and Telegram with intelligent fallback routing.


    ## Features


    * **Multi-Provider Support**: Send messages via SMS, WhatsApp, or Telegram

    * **Smart Fallback Routes**: Automatic provider switching for maximum
    delivery success

    * **Verification Codes**: Automated OTP delivery with customizable codes

    * **Custom Messages**: Send personalized messages with custom sender IDs

    * **Rate Limiting**: Built-in protection against abuse

    * **Spending Controls**: Configurable spending thresholds and credit
    management

    * **Real-time Tracking**: Monitor message delivery status

    * **Sender ID Management**: Register and manage custom sender IDs

    * **Webhook Notifications**: Real-time delivery status updates via webhooks


    ## Provider Options


    OTPIQ now offers 6 provider options including smart fallback routes:

    - **`whatsapp-sms`**: Try WhatsApp first, fallback to SMS

    - **`telegram-sms`**: Try Telegram first, fallback to SMS

    - **`whatsapp-telegram-sms`**: Try WhatsApp → Telegram → SMS (maximum
    delivery success)

    - **`sms`**: SMS only

    - **`whatsapp`**: WhatsApp only

    - **`telegram`**: Telegram only


    ## Authentication


    All API requests require authentication using your project API key. Include
    it in the Authorization header:

    ```

    Authorization: Bearer sk_live_your_api_key_here

    ```


    ## Webhooks


    OTPIQ provides real-time delivery status notifications via webhooks. See the
    Webhooks section for detailed documentation and examples.


    ## Support


    * **Documentation**: [https://docs.otpiq.com](https://docs.otpiq.com)

    * **Support Email**: info@otpiq.com
  version: 1.0.0
  contact:
    name: OTPIQ Support
    url: https://otpiq.com
    email: info@otpiq.com
  license:
    name: Commercial
    url: https://otpiq.com/terms
servers:
  - url: https://api.otpiq.com/api
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: API key authentication and project information
  - name: SMS
    description: >-
      Send SMS messages, verification codes, and track delivery with multiple
      provider options and fallback routing
  - name: Sender IDs
    description: Manage custom sender IDs for your messages
  - name: Webhooks
    description: Real-time delivery status notifications via webhooks
  - name: Delivery Reports
    description: Generate and list CSV delivery reports for SMS/messages in a date range
  - name: Pricing
    description: Retrieve international SMS pricing information
  - name: WhatsApp
    description: >-
      List WhatsApp businesses, accounts, phone numbers, and message templates
      connected to a project
externalDocs:
  description: OTPIQ Documentation
  url: https://docs.otpiq.com
paths:
  /whatsapp/resources:
    get:
      tags:
        - WhatsApp
      summary: List WhatsApp resources
      description: >-
        Returns all WhatsApp resources linked to the project that owns the API
        key: connected Meta businesses, WhatsApp Business Accounts (WABAs),
        phone numbers, and message templates. The project is resolved from the
        API key—you do not pass a project ID in the URL.
      operationId: listWhatsAppResources
      parameters:
        - name: includeTemplateComponents
          in: query
          required: false
          schema:
            type: boolean
            default: false
            example: true
          description: >-
            When `true`, each template includes its full `components` array
            (header, body, buttons, etc.). When `false`, only template metadata
            is returned. Accepted values: `true`, `false`, `1`, `0`
            (case-insensitive).
      responses:
        '200':
          description: WhatsApp resources retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    examples:
                      - true
                  data:
                    type: object
                    required:
                      - project
                      - summary
                      - businesses
                    properties:
                      project:
                        type: object
                        required:
                          - id
                          - slug
                          - name
                        properties:
                          id:

```
Tokens:
Raw