{
 "openapi": "3.0.3",
 "info": {
  "title": "ArabyBot WhatsApp send API",
  "version": "1.0.0",
  "description": "Send an approved WhatsApp template or a 24-hour text from your own system, and read a message's status. As it runs on 2026-11-16. Key (abk_…) from Developer tools in the dashboard. Docs: https://arabybot.com/developers"
 },
 "servers": [
  {
   "url": "https://app.arabybot.com"
  }
 ],
 "security": [
  {
   "SendKey": []
  }
 ],
 "components": {
  "securitySchemes": {
   "SendKey": {
    "type": "http",
    "scheme": "bearer",
    "description": "The send key (abk_…). Also accepted in the X-Api-Key header."
   }
  }
 },
 "paths": {
  "/api/v1/messages/template": {
   "post": {
    "summary": "Send a WhatsApp template via API: fields and refusals",
    "description": "With one POST request to the messages/template address of ArabyBot's send API, carrying the recipient's number with its country code, the template name and the values of its variables, with the send key in the header. The response returns the message id and its status: accepted if WhatsApp took it, or queued if it is waiting its turn. Before the request reaches WhatsApp the values are checked against the approved template itself, so a missing one is refused once with a message that names it. Reference: https://arabybot.com/guides/api-send-whatsapp-template",
    "operationId": "api_send_whatsapp_template",
    "responses": {
     "200": {
      "description": "Success"
     },
     "422": {
      "description": "NO_TEMPLATE: The template name was not put in template. | BAD_VALUES: A value is missing or does not match the approved template, such as an absent variable or the picture of a picture header. | BAD_PHONE: The recipient number is not valid; write it with the country code. | META_REFUSED: WhatsApp refused the message; Meta's code is in meta_code and its text in meta_message."
     },
     "404": {
      "description": "TEMPLATE_NOT_FOUND: No template with this name (and this language, if given) on the number."
     },
     "409": {
      "description": "TEMPLATE_NOT_APPROVED: The template is in review, rejected or paused; its state is in template_status. | OPTED_OUT: The customer turned off marketing messages in WhatsApp, so marketing templates cannot reach them. | NO_NUMBER: No WhatsApp number is connected to the account, or the number in from is not one of its numbers."
     },
     "400": {
      "description": "BAD_JSON: The request body is not valid JSON."
     },
     "402": {
      "description": "MONTHLY_LIMIT: The account reached its plan's monthly sending limit. | SUBSCRIPTION_EXPIRED: The account's subscription has ended."
     },
     "503": {
      "description": "TRY_AGAIN: WhatsApp is busy or the message could not be recorded for a moment; repeat the same request with the same reference after a minute."
     },
     "401": {
      "description": "NO_KEY: The key was not sent in the header. | INVALID_KEY: The key is wrong or was revoked; create one under «Developer tools»."
     },
     "403": {
      "description": "NOT_IN_PLAN: The account's plan does not include «Developer tools»."
     },
     "429": {
      "description": "The key passed 600 requests a minute; wait the time written in the Retry-After header."
     },
     "500": {
      "description": "SERVER: A failure on our side; try again, and tell support if it repeats."
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "to": {
          "type": "string",
          "description": "The recipient's number with its country code, e.g. 966501234567."
         },
         "template": {
          "type": "string",
          "description": "The template name as it is in WhatsApp. Your template names come back from the templates address."
         },
         "language": {
          "type": "string",
          "description": "The template language, e.g. ar or en."
         },
         "variables": {
          "type": "array",
          "description": "The values of the template body's variables, a list by order or by the variables' names.",
          "items": {
           "type": "string"
          }
         },
         "header": {
          "type": "string",
          "description": "The template header's value: the link of the image, video or document, or the text of its variable."
         },
         "buttons": {
          "type": "array",
          "description": "The values of the template's variable buttons, a list.",
          "items": {
           "type": "string"
          }
         },
         "from": {
          "type": "string",
          "description": "The number to send from when the account has more than one; otherwise the default number."
         },
         "reference": {
          "type": "string",
          "description": "A reference from your system, up to a hundred characters, such as the order number plus the notice type. It prevents sending the message twice."
         }
        },
        "required": [
         "to",
         "template"
        ]
       }
      }
     }
    }
   }
  },
  "/api/v1/messages/text": {
   "post": {
    "summary": "Send a WhatsApp text via API, and the 24-hour window",
    "description": "With a POST request to the messages/text address carrying the recipient's number and the message text, up to 4,096 characters, with the send key in the header. Free text is accepted within 24 hours of the customer's last message, Meta's rule and not ours; outside that time you send an approved template. So it suits your system answering a customer who has just written to you. Reference: https://arabybot.com/guides/api-send-whatsapp-text",
    "operationId": "api_send_whatsapp_text",
    "responses": {
     "200": {
      "description": "Success"
     },
     "422": {
      "description": "NO_TEXT: The message was not put in text. | TEXT_TOO_LONG: The text is longer than 4,096 characters. | BAD_PHONE: The recipient number is not valid; write it with the country code. | META_REFUSED: WhatsApp refused the message; Meta's code is in meta_code and its text in meta_message."
     },
     "400": {
      "description": "BAD_JSON: The request body is not valid JSON."
     },
     "402": {
      "description": "MONTHLY_LIMIT: The account reached its plan's monthly sending limit. | SUBSCRIPTION_EXPIRED: The account's subscription has ended."
     },
     "409": {
      "description": "NO_NUMBER: No WhatsApp number is connected to the account, or the number in from is not one of its numbers."
     },
     "503": {
      "description": "TRY_AGAIN: WhatsApp is busy or the message could not be recorded for a moment; repeat the same request with the same reference after a minute."
     },
     "401": {
      "description": "NO_KEY: The key was not sent in the header. | INVALID_KEY: The key is wrong or was revoked; create one under «Developer tools»."
     },
     "403": {
      "description": "NOT_IN_PLAN: The account's plan does not include «Developer tools»."
     },
     "429": {
      "description": "The key passed 600 requests a minute; wait the time written in the Retry-After header."
     },
     "500": {
      "description": "SERVER: A failure on our side; try again, and tell support if it repeats."
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "to": {
          "type": "string",
          "description": "The recipient's number with its country code."
         },
         "text": {
          "type": "string",
          "description": "The message text, up to 4,096 characters."
         },
         "from": {
          "type": "string",
          "description": "The number to send from when the account has more than one."
         },
         "reference": {
          "type": "string",
          "description": "A reference from your system, up to a hundred characters, that prevents sending twice."
         }
        },
        "required": [
         "to",
         "text"
        ]
       }
      }
     }
    }
   }
  },
  "/api/v1/messages/{id}": {
   "get": {
    "summary": "WhatsApp message status via API: delivered, read, failed",
    "description": "With a GET request to the messages address followed by the message id returned when you sent it. The response gives its status now: queued, accepted by WhatsApp, sent, delivered, read or failed; a failed message comes back with Meta's code and the reason. The message's first identifier stays the same even if the queue sent it again. Reference: https://arabybot.com/guides/api-whatsapp-message-status",
    "operationId": "api_whatsapp_message_status",
    "responses": {
     "200": {
      "description": "Success"
     },
     "404": {
      "description": "NOT_FOUND: No message with this id on this account."
     },
     "401": {
      "description": "NO_KEY: The key was not sent in the header. | INVALID_KEY: The key is wrong or was revoked; create one under «Developer tools»."
     },
     "402": {
      "description": "SUBSCRIPTION_EXPIRED: The account's subscription has ended."
     },
     "403": {
      "description": "NOT_IN_PLAN: The account's plan does not include «Developer tools»."
     },
     "429": {
      "description": "The key passed 600 requests a minute; wait the time written in the Retry-After header."
     },
     "500": {
      "description": "SERVER: A failure on our side; try again, and tell support if it repeats."
     }
    },
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  },
  "/api/v1/templates": {
   "get": {
    "summary": "List WhatsApp templates via API: names and status",
    "description": "With a GET request to the templates address. The response returns the number's templates: each one's name, language, category, state at Meta and body text, and with each a ready example request with its fields and variables that you copy to the send address. The list is refreshed from Meta when you ask. Reference: https://arabybot.com/guides/api-whatsapp-templates-list",
    "operationId": "api_whatsapp_templates_list",
    "responses": {
     "200": {
      "description": "Success"
     },
     "409": {
      "description": "NO_NUMBER: No WhatsApp number is connected to the account, or the number in from is not one of its numbers."
     },
     "401": {
      "description": "NO_KEY: The key was not sent in the header. | INVALID_KEY: The key is wrong or was revoked; create one under «Developer tools»."
     },
     "402": {
      "description": "SUBSCRIPTION_EXPIRED: The account's subscription has ended."
     },
     "403": {
      "description": "NOT_IN_PLAN: The account's plan does not include «Developer tools»."
     },
     "429": {
      "description": "The key passed 600 requests a minute; wait the time written in the Retry-After header."
     },
     "500": {
      "description": "SERVER: A failure on our side; try again, and tell support if it repeats."
     }
    },
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "The number whose templates you want when the account has more than one; otherwise the default number.",
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  },
  "/api/v1/me": {
   "get": {
    "summary": "Check a WhatsApp API key and its numbers",
    "description": "With a GET request to the me address. The response returns the key's name and the WhatsApp numbers connected to the account, and which is the default number messages leave from when you name none. It is the first request to try after creating the key, because it sends nothing and costs nothing. Reference: https://arabybot.com/guides/api-whatsapp-key-check",
    "operationId": "api_whatsapp_key_check",
    "responses": {
     "200": {
      "description": "Success"
     },
     "401": {
      "description": "NO_KEY: The key was not sent in the header. | INVALID_KEY: The key is wrong or was revoked; create one under «Developer tools»."
     },
     "402": {
      "description": "SUBSCRIPTION_EXPIRED: The account's subscription has ended."
     },
     "403": {
      "description": "NOT_IN_PLAN: The account's plan does not include «Developer tools»."
     },
     "429": {
      "description": "The key passed 600 requests a minute; wait the time written in the Retry-After header."
     },
     "500": {
      "description": "SERVER: A failure on our side; try again, and tell support if it repeats."
     }
    }
   }
  }
 }
}