---
name: Notifique
description: Use when building multi-channel messaging integrations, sending transactional or marketing notifications via WhatsApp, SMS, email, push, RCS, or Telegram. Reach for this skill when implementing message templates, managing API keys and scopes, setting up webhooks for delivery tracking, or managing contacts and campaigns.
metadata:
    mintlify-proj: notifique
    version: "1.0"
---

# Notifique Skill

## Product summary

Notifique is a unified messaging infrastructure API that handles sending and receiving messages across multiple channels (WhatsApp, SMS, email, push, RCS, Telegram) from a single REST API. Agents use Notifique to send transactional notifications, marketing campaigns, and manage message delivery at scale. Key files and concepts: API Keys (created in dashboard, never via API), templates (reusable message configurations with variables), webhooks (event delivery tracking), and workspaces (isolated environments with their own credits and resources). Primary docs: https://docs.notifique.dev

## When to use

Reach for this skill when:
- Building message sending integrations (transactional alerts, OTP codes, order confirmations, marketing campaigns)
- Implementing multi-channel campaigns (same message to WhatsApp, SMS, and email in one API call)
- Setting up delivery tracking and status monitoring via webhooks
- Managing API authentication with scoped keys and resource restrictions
- Creating reusable message templates with variable substitution
- Handling contact management, segmentation, or audience targeting
- Troubleshooting message delivery failures or API errors
- Configuring domain verification for email sending
- Managing WhatsApp instances or other channel-specific setup

## Quick reference

### API Key authentication
Send in every request via header:
```
Authorization: Bearer sk_live_xxxxx
```
or
```
x-api-key: sk_live_xxxxx
```

### Core endpoints by channel

| Channel | Send endpoint | Status check | Notes |
|---------|---------------|--------------|-------|
| WhatsApp | `POST /v1/whatsapp/messages` | `GET /v1/whatsapp/messages/{id}` | Requires active instance |
| SMS | `POST /v1/sms/send` | `GET /v1/sms/{id}` | Max 160 chars, min 9 chars |
| Email | `POST /v1/email/send` | `GET /v1/email/{id}` | Requires verified domain |
| Push | `POST /v1/push/send` | `GET /v1/push/{id}` | Requires registered device |
| Templates | `POST /v1/templates/send` | Via channel endpoints | Multi-channel in one call |

### Common request fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `to` | array | Yes | Phone numbers (E.164) or emails; max 100 per request |
| `message` / `subject` / `payload` | string/object | Yes | Content varies by channel |
| `instanceId` | string | If no default | WhatsApp instance ID |
| `from` | string | If no default | Email sender (verified domain) |
| `variables` | object | If template | Template variable substitution |
| `channels` | array | If template | `["whatsapp", "sms", "email"]` |
| `schedule.sendAt` | ISO 8601 | No | Schedule message for future delivery |

### Response codes

| Code | Meaning | Action |
|------|---------|--------|
| 202 | Accepted (queued) | Message enqueued; check status via webhook or polling |
| 400 | Bad Request | Validate payload, required fields, format (SMS min 9 chars) |
| 401 | Unauthorized | Check API Key validity and format |
| 402 | Payment Required | Insufficient credits/balance or plan expired |
| 403 | Forbidden | Missing scope, resource not allowed, or plan limit |
| 404 | Not Found | Resource doesn't exist or wrong workspace |
| 409 | Conflict | Duplicate (e.g., contact phone already exists) |

### Webhook event types

| Event | Channel | Meaning |
|-------|---------|---------|
| `message.sent` | WhatsApp | Message accepted by provider |
| `message.delivered` | WhatsApp | Message reached device |
| `message.read` | WhatsApp | Recipient opened message |
| `message.failed` | WhatsApp | Send failed |
| `sms.sent` | SMS | SMS accepted |
| `sms.delivered` | SMS | SMS delivered |
| `sms.failed` | SMS | SMS failed |
| `email.sent` | Email | Email accepted |
| `email.delivered` | Email | Email delivered |
| `email.opened` | Email | Recipient opened email |
| `email.clicked` | Email | Recipient clicked link |
| `push.sent` | Push | Push accepted |
| `push.delivered` | Push | Push delivered to device |
| `push.clicked` | Push | User clicked notification |

### Credit consumption

| Channel | Credits per message | Real cost (pay-as-you-go) |
|---------|---------------------|--------------------------|
| WhatsApp | 1 | R$ 0.05 |
| SMS | 30 | R$ 0.12 |
| Email | 1 | R$ 0.05 |
| Push | 1 | R$ 0.05 |
| RCS | 60 | R$ 0.25 |

## Decision guidance

### When to use templates vs. direct channel API

| Scenario | Use templates | Use direct API |
|----------|---------------|----------------|
| Send same message to multiple channels | ✓ | ✗ |
| Single-channel, one-off messages | ✗ | ✓ |
| Reusable message configurations | ✓ | ✗ |
| Dynamic content per recipient | ✓ | ✓ |
| Simple text alerts | ✗ | ✓ |

### When to use API Key scopes

| Use case | Scopes | Rationale |
|----------|--------|-----------|
| Production notification service | `whatsapp:send`, `sms:send`, `email:send` | Least privilege; send-only |
| Admin dashboard | `whatsapp:manage`, `sms:read`, `email:read` | Read + manage instances/domains |
| Webhook management | `webhooks:read`, `webhooks:manage` | Isolated webhook operations |
| Audit/logging | `logs:read` | Read-only access to API logs |
| Multi-tenant (per-client) | Restrict `instanceIds`, `domainIds` | Prevent cross-client access |

### When to schedule vs. send immediately

| Condition | Action |
|-----------|--------|
| Time-sensitive (OTP, alert) | Send immediately (no `schedule.sendAt`) |
| Marketing campaign (batch) | Schedule for optimal delivery time |
| Recurring notification | Use automations or external scheduler |
| Plan doesn't support scheduling | Send immediately (403 `PLAN_LIMIT_SCHEDULING`) |

## Workflow

### 1. Send a simple message (SMS example)

1. **Verify prerequisites:** API Key with `sms:send` scope, account has credits/balance.
2. **Prepare payload:**
   ```json
   {
     "to": ["5511999999999"],
     "message": "Your code is 123456"
   }
   ```
3. **Send request:** `POST /v1/sms/send` with Authorization header.
4. **Check response:** 202 = queued; extract `smsIds` for tracking.
5. **Monitor delivery:** Poll `GET /v1/sms/{smsId}` or listen for `sms.delivered` webhook.

### 2. Send multi-channel template

1. **Create template in dashboard:** Define content for WhatsApp, SMS, email with variables (e.g., `{{name}}`, `{{code}}`).
2. **Verify setup:** Ensure WhatsApp instance is ACTIVE, email domain is verified.
3. **Prepare request:**
   ```json
   {
     "to": ["5511999999999", "user@example.com"],
     "template": "welcome",
     "variables": {"name": "João", "code": "ABC123"},
     "channels": ["whatsapp", "sms", "email"]
   }
   ```
4. **Send:** `POST /v1/templates/send` with API Key.
5. **Parse response:** Returns `messageIds`, `smsIds`, `emailIds` for each channel.
6. **Track status:** Use channel-specific endpoints or webhooks.

### 3. Set up webhook for delivery tracking

1. **Create webhook in dashboard or via API:** `POST /v1/webhooks`
   ```json
   {
     "name": "Delivery Tracker",
     "url": "https://yourapi.com/webhooks/notifique",
     "events": ["message.delivered", "sms.delivered", "email.delivered"],
     "instanceIds": []
   }
   ```
2. **Save webhook secret:** Use for HMAC validation.
3. **Implement endpoint:** Accept POST, validate `X-Notifique-Signature` header.
4. **Validate signature:** `HMAC-SHA256(secret, timestamp + "." + body)`.
5. **Check timestamp:** Reject if outside 5-minute window (anti-replay).
6. **Process event:** Update message status in your database.

### 4. Manage API Key with scopes

1. **Go to dashboard:** API Keys section.
2. **Create new key:** Set name, select scopes (e.g., `whatsapp:send`, `sms:send`).
3. **Restrict resources (optional):** Limit to specific WhatsApp instances or email domains.
4. **Copy key immediately:** Not shown again; store in `.env` or secrets manager.
5. **Use in code:** Pass in Authorization header or `x-api-key`.
6. **Rotate periodically:** Create new key, update code, revoke old key.

### 5. Troubleshoot delivery failure

1. **Check API response:** 202 = queued (not failed yet); check status endpoint.
2. **Review error code:** `SMS_MESSAGE_TOO_SHORT`, `DOMAIN_NOT_VERIFIED`, `INSUFFICIENT_CREDITS`, etc.
3. **Verify prerequisites:** API Key scope, instance/domain active, credits available.
4. **Check webhook events:** Look for `message.failed`, `sms.failed`, `email.failed` with reason.
5. **Review logs:** `GET /v1/logs` shows request/response history with duration.
6. **Validate payload:** Ensure `to` format (E.164 for phone, valid email), required fields present.

## Common gotchas

- **API Key shown only once:** Copy immediately on creation; cannot be recovered. Generate new if lost.
- **SMS minimum length:** Must be at least 9 characters; max 160. Shorter messages return 400 `SMS_MESSAGE_TOO_SHORT`.
- **Email domain not verified:** Sending from unverified domain returns 400 `DOMAIN_NOT_VERIFIED`. Verify DNS records first.
- **WhatsApp instance required:** No default instance = 400 error. Either set default in workspace or pass `instanceId` in every request.
- **Template variables missing:** If template requires `{{name}}` but you don't send it in `variables`, API returns 400 with `missingVariables` list.
- **Duplicate SMS detection:** Sending identical SMS to same number within 1 minute returns 400 `SMS_DUPLICATE_RECENT`. Use idempotency key or wait.
- **Insufficient credits:** 402 `INSUFFICIENT_CREDITS` = no credits left. Recharge balance or upgrade plan.
- **Webhook signature validation:** Always validate `X-Notifique-Signature` header; don't trust webhook content without verification.
- **Webhook timeout:** 10-second timeout per request. Respond quickly; process async if needed.
- **Idempotency key:** Use `Idempotency-Key` header to prevent duplicate sends on retry; valid 24 hours.
- **Contact phone uniqueness:** Each phone number is unique per workspace. Duplicate phone = 409 `CONTACT_PHONE_EXISTS`.
- **Scheduling limits:** Some plans don't support scheduling; check plan before using `schedule.sendAt`.
- **Multi-tenant isolation:** API Key restricted to specific instances/domains won't access others; returns 403 `DOMAIN_NOT_ALLOWED` or `PUSH_APP_NOT_ALLOWED`.

## Verification checklist

Before submitting work with Notifique:

- [ ] API Key is valid and has required scopes for the operation (e.g., `whatsapp:send` for WhatsApp).
- [ ] Payload is valid: `to` field populated, required fields present, SMS 9–160 chars.
- [ ] WhatsApp instance is ACTIVE (if using WhatsApp); email domain is verified (if using email).
- [ ] Default instance/domain set in workspace OR explicitly passed in request (`instanceId`, `from`).
- [ ] Credits/balance sufficient for the operation (check workspace balance).
- [ ] Template exists and has content for requested channels (if using templates).
- [ ] Template variables match what's sent in `variables` object (no missing required vars).
- [ ] Webhook URL is accessible and responds within 10 seconds (if setting up webhooks).
- [ ] Webhook signature validation implemented (HMAC-SHA256 with secret).
- [ ] Error handling covers 400, 401, 402, 403, 404, 409 responses.
- [ ] Idempotency key used for critical operations (to prevent duplicates on retry).
- [ ] Message status tracked via webhook or polling endpoint.
- [ ] Logs reviewed for any warnings or unexpected behavior (`GET /v1/logs`).

## Resources

- **Comprehensive navigation:** https://docs.notifique.dev/llms.txt
- **Getting started:** https://docs.notifique.dev/comece-aqui
- **API Key management:** https://docs.notifique.dev/introducao-api-key
- **Templates & multi-channel:** https://docs.notifique.dev/a-magia-dos-templates
- **Webhooks & events:** https://docs.notifique.dev/introducao-webhooks
- **Error codes & troubleshooting:** https://docs.notifique.dev/erros

---

> For additional documentation and navigation, see: https://docs.notifique.dev/llms.txt