Concepts and Identifiers

Tenant Scope

The API key identifies one Notify Africa customer account. Every template and message operation is scoped to that owner. Webhook management, including queuing a test delivery, is a Portal-session (JWT) operation, not an API-key operation, but stays scoped to the same account.

The Developer API resolves the connected WhatsApp assets. Send requests do not accept caller-selected business, WABA, or phone-number IDs.

Identifiers

Identifier	Owner	Where it appears	Use
API key	Notify Africa	Bearer header	Authentication and tenant scope
Business ID	Meta	Portal/account metadata	Meta business identity
WABA ID	Meta	Template metadata and template events	WhatsApp Business Account identity
Phone-number ID	Meta	Portal/account metadata	Selected sending number
`templateId`	Notify Africa UUID	Template responses and paths	Retrieve, update, validate, preview, sync, delete
External template ID	Meta	`whatsappConfig.externalTemplateId`	Provider diagnostics
External template name	Meta	Template create response and send body	`template_name` for template sends
`messageId`	Notify Africa	Send results and message events	Internal correlation
`wamid`	Meta	Send results when available and message events	Provider correlation
`webhookId`	Notify Africa UUID	Portal and webhook-test path	Select an owned callback endpoint
`eventId`	Notify Africa UUID	Every callback	Receiver deduplication
`aggregateId`	Notify Africa/provider-derived	Every callback	Resource referenced by the event
`dedupeKey`	Notify Africa	Every callback	Event-production correlation

Do not use a Meta identifier where a Notify Africa UUID is required.

Template States

State	Meaning
`pending`	Meta review is pending, provider status is absent, or provider status is not in the public status vocabulary
`approved`	Template can be used for template sends
`rejected`	Meta rejected the template; inspect status diagnostics

Raw provider state remains available in whatsappConfig.providerStatus. Rejection, disable, or lock diagnostics can appear in whatsappConfig.statusInfo.

Synchronization States

State	Meaning
`null`	No synchronization attempt is recorded
`stale`	Local projection requires refresh
`synced`	Latest provider projection was stored
`failed`	Last refresh failed; inspect `lastSyncError`

Template approval state and synchronization state are separate.

Message States

State	Meaning
`queued` or `processing`	Accepted for asynchronous processing
`sending`	Provider submission is in progress
`accepted`	Provider accepted the request
`sent`	Provider reports sent
`delivered`	Recipient device received the message
`read`	Recipient read the message
`failed`	Processing or provider delivery failed
`received`	Inbound customer message
`unknown`	Provider state is not mapped

The initial HTTP response does not guarantee a terminal state.

Webhook Delivery States

Delivery inspection is available in the Portal.

State	Meaning
`pending`	Waiting for the first attempt
`delivering`	Claimed by a dispatcher
`delivered`	Endpoint returned HTTP 2xx
`retrying`	Retryable failure with another attempt scheduled
`failed`	Attempts or the 24-hour retry window were exhausted
`discarded`	Permanent failure; no additional attempt will run