SDK vs REST

The Convoup SDK is a convenience layer over the REST API. This page explains when to use each approach.

When to Use the SDK

Use the SDK when:

You are building a Node.js or TypeScript application
You want typed method signatures and autocompletion
You want automatic payload construction from template names
You want structured error handling with ConvoupError
You want to minimize boilerplate

TypeScript

import { Convoup } from 'convoup';

const client = new Convoup({ apiKey: process.env.CONVOUP_API_KEY! });

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

When to Use the REST API

Use the REST API when:

You are not using Node.js (Python, Go, Ruby, etc.)
You need endpoints the SDK doesn't wrap yet (e.g., POST /api/v1/messages)
You want full control over the request body
You are debugging or testing raw payloads

bash

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"}]
  }'

Method-to-Endpoint Mapping

SDK Method	REST Endpoint	Method
`client.sendOtp()`	`/api/v1/templates`	`POST`
`client.sendInvoice()`	`/api/v1/templates`	`POST`
`client.sendReminder()`	`/api/v1/templates`	`POST`
`client.sendTemplate()`	`/api/v1/templates`	`POST`
(SDK does not wrap)	`/api/v1/messages`	`POST`
(SDK does not wrap)	`/api/v1/templates`	`GET`
(SDK does not wrap)	`/api/v1/contacts/window-status`	`GET`

All four SDK methods map to the same POST /api/v1/templates endpoint with different parameter construction.

Key Differences

Aspect	SDK	REST
Authentication	Pass `apiKey` in constructor	Pass `x-api-key` header per request
Payload construction	Typed params (`to`, `template`, `code`)	Manual JSON body
Error handling	`ConvoupError` with `status`, `code`, `details`	Parse response JSON yourself
Language default	`en_US`	Must specify `language` in body
Type safety	Full TypeScript types	None (unless you define them)

Example: Same Call in Both Approaches

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

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"}]
  }'

Next Steps

Client Constructor - Full SDK initialization options
REST Endpoints - Raw HTTP API reference
Language Support - Multi-language template sending