Create a WhatsApp Template with OAuth 2.0

You can use the WhatsApp Template Management API to create a new managed WhatsApp template with OAuth 2.0. You can use this API version if you authenticate requests with an OAuth 2.0.

Field naming rule

The token generation request uses snake_case fields, such as client_id and client_secret. Template CRUD request bodies use camelCase fields, such as name, language, category, and components.

Endpoint and Headers

POST https://gw.useinsider.com/api/wa/v2/templates

Headers

Body Parameters

Sample Requests

Generate a Gateway Access Token

Before calling the OAuth 2.0 template endpoints, generate a Gateway access token.

curl --location 'https://gw.useinsider.com/auth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "scopes": ["wa-temp-read", "wa-temp-manage", "wa-temp-delete"]
}'

Basic Marketing Template with Quick Reply Button

curl --location 'https://gw.useinsider.com/api/wa/v2/templates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-oauth2-token' \
--data '{
  "name": "spring_campaign_template",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, our new spring collection is live now. Tap below to explore best sellers picked for you."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Show products"
        }
      ]
    }
  ]
}'

Utility Template with Header, Body, Footer, and URL Button

curl --location 'https://gw.useinsider.com/api/wa/v2/templates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-oauth2-token' \
--data '{
  "name": "order_delivery_update",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Order update"
    },
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order {{2}} is on the way and will arrive on {{3}}."
    },
    {
      "type": "FOOTER",
      "text": "Thank you for shopping with us."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Track package",
          "url": "https://tracking.example.com/orders/{{2}}"
        }
      ]
    }
  ]
}'

Create an Authentication Template with Security Code

curl --location 'https://gw.useinsider.com/api/wa/v2/templates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-oauth2-token' \
--data '{
  "name": "login_code_template",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "text": "*{{1}}* is your verification code. For your security, do not share this code."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Copy code"
        }
      ]
    }
  ]
}'

Upload an Image to the Header

If you want to create a media template,

1. Upload the asset first through Gateway and reuse the returned handle in the create request.

curl --location 'https://gw.useinsider.com/api/wa/v2/templates/file-upload' \
--header 'Authorization: Bearer your-oauth2-token' \
--form 'file=@"/path/to/spring-banner.png"'

2. You will receive the sample response below to your upload request.

{
  "id": "4::aW1hZ2UvcG5n:ARbExampleMediaHandle"
}

3. After the upload completes, send the create request to the Gateway template endpoint with an image header component.

curl --location 'https://gw.useinsider.com/api/wa/v2/templates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-oauth2-token' \
--data '{
  "name": "spring_visual_campaign",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_handle": [
          "4::aW1hZ2UvcG5n:ARbExampleMediaHandle"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Hi {{1}}, our spring collection is now live. Tap below to browse the new arrivals."
    },
    {
      "type": "BUTTONS", 
      "buttons": [
        {
          "type": "URL",
          "text": "Shop now",
          "url": "https://www.example.com/spring"
        }
      ]
    }
  ]
}'

Sample Responses

A successful request returns the following JSON response with the details of the newly created template.

{
  "id": 42,
  "name": "spring_campaign_template",
  "language": "en_US",
  "quality": "PENDING",
  "status": "IN-REVIEW"
}

{
  "message": "invalid client credentials"
}

{
  "message": "unauthorized"
}

{
  "message": "forbidden"
}

{
  "message": "failed to decode request"
}

{
  "message": "failed to validate request",
  "error": "Key: 'CreateRequest.Name' Error:Field validation for 'Name' failed on the 'required' tag"
}

{
  "message": "failed to validate request",
  "error": "Key: 'CreateRequest.Components' Error:Field validation for 'Components' failed on the 'min' tag"
}

{ "message": "page must be a positive integer" }
{ "message": "per_page must be between 1 and 100" }
{ "message": "sort must be in column|direction format" }
{ "message": "sort column is invalid" }
{ "message": "sort direction is invalid" }

{
  "message": "template id is invalid"
}

{
  "message": "template not found"
}

{
  "message": "active whatsapp router domain not found"
}

{
  "message": "Invalid parameter - buttons: quick reply and url combination is not supported"
}

{
  "message": "file is required"
}

{
  "message": "upload rate limit exceeded"
}

{
  "message": "Unsupported post request. Object with ID 'upload-session-id' does not exist"
}

{ "message": "failed to decode template creation response" }
{ "message": "template created in Meta but could not be persisted locally" }