convoup Docs
Sign in Start free
Docs / API Reference / Template Discovery

Template Discovery

Before sending, you can programmatically discover which templates are available and what parameters each one needs.

List All Approved Templates

bash
curl https://api.convoup.com/api/v1/templates \
  -H "x-api-key: YOUR_API_KEY"
TypeScript
const res = await fetch('https://api.convoup.com/api/v1/templates', {
  headers: { 'x-api-key': process.env.CONVOUP_API_KEY! },
});
const { data: templates } = await res.json();

Response Shape

JSON
{
  "success": true,
  "data": [
    {
      "id": "tmpl_abc123",
      "name": "test_welcome_template",
      "language": "en_US",
      "category": "TRANSACTIONAL",
      "components": [
        { "type": "HEADER", "format": "TEXT", "text": "Welcome to {{1}}!" },
        { "type": "BODY", "text": "Hi {{1}}, your OTP is {{2}}." },
        { "type": "FOOTER", "text": "Powered by Convoup" },
        { "type": "BUTTONS" }
      ],
      "parameters": [
        {
          "position": 1,
          "name": "company_name",
          "example": "Acme Corp",
          "description": "Company name shown in header and greeting"
        },
        {
          "position": 2,
          "name": "otp_code",
          "example": "123456",
          "description": "The one-time password to display"
        }
      ]
    }
  ]
}

Using Discovery to Build Dynamic Sends

TypeScript
const res = await fetch('https://api.convoup.com/api/v1/templates', {
  headers: { 'x-api-key': apiKey },
});
const { data: templates } = await res.json();

const template = templates.find(t => t.name === 'test_welcome_template');
console.log(`Template has ${template.parameters.length} params:`);
template.parameters.forEach(p => {
  console.log(`  Position ${p.position}: ${p.name} - ${p.description}`);
});

// Now send with confidence
await client.sendOtp({
  to: '+918851479441',
  template: 'test_welcome_template',
  code: '123456',
  extraParams: ['Acme Corp'],
});

Flow

graph LR A[GET /api/v1/templates] --> B[Receive template list] B --> C[Find template by name] C --> D[Read parameter positions] D --> E[Build send call with correct params] E --> F[POST /api/v1/templates]

Why Use Discovery

Next Steps