FAQ & Troubleshooting

Common issues and solutions for the Convoup SDK.

Installation & Setup

npm install convoup fails

node --version  # Should be v18.0.0 or higher

Convoup is not a constructor

Make sure you are importing from the correct module:

// Correct
import { Convoup } from 'convoup';

// Wrong
const Convoup = require('convoup');

Authentication

401 Unauthorized on every request

1. Verify your API key in the Convoup dashboard
2. Check for extra whitespace or newline characters in your environment variable
3. Ensure the key is set as a server-side environment variable, not in client code

// Debug: check what key is being used (never log this in production!)
console.log('Key starts with:', process.env.CONVOUP_API_KEY?.substring(0, 8));

WABA ID required error

Your API key has access to multiple WABAs. Pass the wabaId:

const client = new Convoup({
  apiKey: process.env.CONVOUP_API_KEY!,
  wabaId: 'your-waba-id',
});

Templates

TEMPLATE_NOT_FOUND

• The template name is case-sensitive: test_welcome_template != Test_Welcome_Template
• Verify the exact name in the Convoup dashboard or via GET /api/v1/templates
• Ensure the template is approved, not just created

TEMPLATE_PARAM_MISMATCH

The number of params you provided doesn't match the template's placeholders:

// If template body is "Hi {{1}}, your OTP is {{2}}"
// Correct: 2 params
bodyParams: ['Rahul', '123456']

// Wrong: 1 param
bodyParams: ['Rahul']

Use template discovery to check parameter count:

curl https://api.convoup.com/api/v1/templates \
  -H "x-api-key: YOUR_API_KEY"

TEMPLATE_REQUIRED when using sendText()

You can only send free-form text within a 24-hour window after the customer messages you. Outside this window, you must use an approved template:

// Instead of sendText(), use sendOtp or sendTemplate
await client.sendTemplate({
  to: '+918851479441',
  template: 'follow_up_template',
  language: 'en_US',
  bodyParams: ['Your message here'],
});

Messages

RECIPIENT_SUPPRESSED

The recipient has blocked your WhatsApp number or is on the suppression list. Remove this number from your list and do not retry.

Messages not delivering

• Check the messageId in your dashboard for delivery status
• Ensure the recipient's phone number is in international format with country code
• Verify the template is approved and the language matches
• Check that the 24h window is open for sendText() calls

Language

Template not found in specific language

The template must be approved in that specific language. Check available languages in the dashboard:

await client.sendOtp({
  to: '+918851479441',
  template: 'test_welcome_template',
  code: '123456',
  language: 'hi_IN', // Must be approved for Hindi
});

Performance

Rate limiting

Slow responses in bulk sending

When sending to many recipients, use Promise.allSettled() with concurrency control rather than sending all at once:

import pLimit from 'p-limit';
const limit = pLimit(10); // 10 concurrent sends

const results = await Promise.allSettled(
  customers.map(c => limit(() => client.sendOtp({
    to: c.phone,
    template: 'test_welcome_template',
    code: c.code,
  })))
);

Next Steps

• Error Codes - Complete error code reference
• Bulk Sending - Batch sending patterns
• Authentication - API key setup