Edit a WhatsApp Template

You can use the WhatsApp Template Management API to edit an existing managed WhatsApp template in Insider One. Use this API version when you authenticate requests with an Insider One API key.

Editing a template through the API lets you update its content without recreating it, so the template keeps its Insider One template ID. This page covers the endpoint, the parameters, the rules that decide which edits are accepted, and the errors you can handle in your integration.

All examples on this page use sample data and payloads for documentation purposes only. Before you go live, replace all template names, languages, components, and media handles with values specific to your own integration.

For the V1 template API, authenticate requests with the x-ins-auth-key header. The examples use the Gateway base URL, so your integration calls a public entry point.

Endpoint and headers

PUT https://whatsapp.useinsider.com/v1/templates/42

Path parameter

Body parameters

The endpoint rejects any other top-level field, including ttl, with a 400 status.

Which templates you can edit

You can edit only templates in APPROVED, PAUSED, or REJECTED status. The endpoint refuses every other status, including IN-REVIEW.

Edit limits apply to APPROVED templates:

• You can edit an APPROVED template once every 24 hours.

• You can edit an APPROVED template 10 times in 30 days.

• The limits are counted per template, and edits made in Meta’s WhatsApp Manager count toward the same limits.

• PAUSED and REJECTED templates do not count toward the limits.

Edits fall into two types:

• Text-only edit: changes only the header, body, or footer text, or the button labels. Insider One always accepts a text-only edit.

• Structural edit: any other change, including a category change. The endpoint refuses a structural edit while an active, running, or scheduled campaign or journey uses the template.

Sample request

curl --location --request PUT 'https://whatsapp.useinsider.com/v1/templates/42' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: your-api-key' \
--data '{
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order {{2}} has shipped.",
      "example": { "body_text": [["Jane", "A-100"]] }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Track order",
          "url": "https://shop.example.com/track/{{1}}",
          "example": ["https://shop.example.com/track/12345"]
        }
      ]
    }
  ]
}'

Sample response

200 OK

{ "message": "template update accepted" }

Sample error responses

Every failure returns a message field. Edit-specific failures also return an error object with a key value that you can use to branch your logic. Retryable failures include a Retry-After header.

400 Bad Request: invalid template ID

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

400 Bad Request: invalid JSON body or unknown field

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

400 Bad Request: missing components

The response also includes the validator text that describes the failed rule.

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

400 Bad Request: status does not support editing

{
  "message": "template status does not support editing",
  "error": {
    "key": "template-edit-status-not-supported"
  }
}

400 Bad Request: immutable field

The message names the field that you cannot change.

{
  "message": "approved template category cannot be changed",
  "error": {
    "key": "template-edit-immutable-field"
  }
}

404 Not Found

{
  "message": "template not found"
}

409 Conflict

To resolve this error, send a text-only edit, or wait until no active, running, or scheduled campaign or journey uses the template.

{
  "message": "template is in active use and the edit changes its structure",
  "error": {
    "key": "template-edit-structural-blocked"
  }
}

422 Unprocessable Entity: content rejected

{
  "message": "template content was rejected by content validation",
  "error": {
    "key": "template-edit-content-shield-rejected"
  }
}

422 Unprocessable Entity: router domain missing

This error occurs when the template has URL buttons and the account has no active WhatsApp router domain. Contact the Insider team to resolve it.

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

429 Too Many Requests: 24-hour edit limit

{
  "message": "approved template edit 24-hour limit reached",
  "error": {
    "key": "template-edit-quota-exceeded"
  }
}

429 Too Many Requests: 30-day edit limit

{
  "message": "approved template edit 30-day limit reached",
  "error": {
    "key": "template-edit-quota-exceeded"
  }
}

503 Service Unavailable: quota check unavailable

The response includes a Retry-After header. You can retry the same request after the wait time it gives.

{
  "message": "template edit quota is temporarily unavailable",
  "error": {
    "key": "template-edit-quota-unavailable"
  }
}

503 Service Unavailable: dependency unavailable

The response includes a Retry-After header. You can retry the same request after the wait time it gives.

{
  "message": "template edit dependency unavailable",
  "error": {
    "key": "template-edit-usage-unavailable"
  }
}

Meta’s status code: edit rejected by Meta

Insider One returns Meta’s status code and message as is.

{
  "message": "Invalid parameter",
  "error": {
    "key": "template-edit-meta-rejected"
  }
}

502 Bad Gateway: result unknown

{
  "message": "template edit result is unknown",
  "error": {
    "key": "template-edit-meta-rejected"
  }
}

502 Bad Gateway: accepted by Meta but not stored locally

{
  "message": "template edit accepted by Meta but local persistence failed",
  "error": {
    "key": "template-edit-local-persist-failed"
  }
}

Limitations

• The rate limit is 10 requests per second per account.

• The endpoint sends one request to Meta and never retries it.

• The API does not ask for confirmation on a text-only edit of a template that is in use. It applies the edit.