Docs / Quick Start

Quick Start

Get from zero to your first WhatsApp message in under 10 minutes.

Prerequisites

Before you begin, you need:

Node.js 18 or later (the SDK uses the built-in fetch API)
A Convoup API key (create one in the Convoup dashboard under Developers > API Keys)
At least one approved template in your WABA (WhatsApp Business Account)

Check your Node version:

bash

node --version  # v18.0.0 or higher

Install the SDK

bash

npm i convoup

Initialize the Client

Create a .env file in your project root:

.env

CONVOUP_API_KEY=your-api-key-here
CONVOUP_WABA_ID=your-waba-id-here

Then initialize the client in your code:

TypeScript

import { Convoup } from 'convoup';

const client = new Convoup({
  apiKey: process.env.CONVOUP_API_KEY!,
  wabaId: process.env.CONVOUP_WABA_ID, // optional if key is scoped to one WABA
});

Note

The wabaId is only required when your API key has access to multiple WABAs. If it is scoped to exactly one WABA, the server resolves it automatically.

Send Your First Message

Here is a minimal example that sends an OTP template:

await client.sendOtp({
  to: '+918851479441',
  template: 'test_welcome_template',
  code: '123456',
});

// Returns: { messageId: 'meta-msg-abc123', waId: '918851479441' }

curl -X POST https://api.convoup.com/api/v1/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "to": "+918851479441",
    "template_name": "test_welcome_template",
    "language": "en_US",
    "body_params": [{"type": "text", "text": "123456"}]
  }'

What just happened

The SDK built a Meta-compatible payload from your template name and parameters
It sent a POST request to the Convoup API with your API key in the x-api-key header
Convoup forwarded the request to the Meta WhatsApp Cloud API
The response includes a messageId for tracking delivery status

sequenceDiagram participant D as Your App participant C as Convoup API participant M as Meta WhatsApp API participant R as Recipient D->>C: POST /api/v1/templates (x-api-key) C->>M: Forward template message M-->>C: Accepted C-->>D: { messageId, waId } M->>R: Delivers WhatsApp message

Response Format

Every successful send returns:

JSON

{
  "messageId": "meta-msg-abc123",
  "waId": "918851479441"
}

Field	Type	Description
`messageId`	`string`	Meta message ID for tracking delivery status
`waId`	`string`	WhatsApp ID of the recipient (country code + number, no `+`)

Phone Number Format

Always use international format with the country code and a + prefix:

Format	Example	Valid
International	`+918851479441`	Yes
Local	`8851479441`	No
With leading zero	`08851479441`	No

Common Mistake

Using a local number like 8851479441 will return an INVALID_PHONE error. Always include the country code.

What's Next

Authentication - Learn about API key scoping and WABA restrictions
How Templates Work - Understand template structure and placeholders
Sending OTPs - Deep dive into OTP sending with extra parameters