iThinq AI documentation

Everything you need to integrate, configure, and extend our AI solutions.

Getting Started

Welcome to iThinq AI! This guide helps you spin up your first AI assistant in minutes.

  • Sign Up: Create a free account at /signup.
  • Obtain API Key: In your dashboard, navigate to “API Keys” → “Create New Key”. Copy the key to your secure vault.
  • Install SDK: Add our NPM package to your project:
    npm install @ithinq-ai/sdk
  • Initialize: In your server-side code (Node.js example):
    import { IthinqClient } from '@ithinq-ai/sdk';
    
    const client = new IthinqClient({
      apiKey: process.env.ITHINQ_API_KEY,
    });

Integration

Our SDK supports Node.js, Python, and PHP. Below are quick start snippets for each.

Node.js

import { IthinqClient } from '@ithinq-ai/sdk';

(async () => {
  const client = new IthinqClient({ apiKey: process.env.ITHINQ_API_KEY });
  const response = await client.call({
    to: '+1234567890',
    from: '+1098765432',
    script: 'hello_script_id',
    data: { name: 'Alice' },
  });
  console.log('API Response:', response);
})();

Python

from ithinq_sdk import IthinqClient

client = IthinqClient(api_key='YOUR_API_KEY')

response = client.call(
  to='+1234567890',
  from_='+1098765432',
  script='hello_script_id',
  data={'name': 'Alice'}
)
print('API Response:', response)

PHP

require 'vendor/autoload.php';

use Ithinq\IthinqClient;

$client = new IthinqClient('YOUR_API_KEY');

$response = $client->call([
    'to' => '+1234567890',
    'from' => '+1098765432',
    'script' => 'hello_script_id',
    'data' => ['name' => 'Alice']
]);

print_r($response);

Configuration

Customize your AI assistant’s behavior, language, and integration endpoints.

Webhook URL
In your dashboard, go to “Settings” → “Webhooks” and set the endpoint that will handle incoming call data. Example:
https://yourdomain.com/ithinq/webhook
Language & Voice
Choose from our supported voices (English, Urdu, Arabic). In the SDK call, pass:
{
  language: 'en-US',
  voice: 'female1'
}
Time Zone
By default, calls schedule in UTC. To use Asia/Karachi local time, set:
timezone: 'Asia/Karachi'
Retry Policies
Configure how many retry attempts are made on failure. Example config:
{
  retries: 3,
  backoff: 'exponential',
}

API Reference

Below are the key endpoints you’ll interact with. All requests use HTTPS and expect JSON payloads.

POST /v1/call

Initiate a call session. Returns a `callId` and current status.

FieldTypeRequiredDescription
tostringYesDestination phone number (+E.164)
fromstringYesYour verified caller ID
scriptstringYesID of the conversational script to run
dataobjectNoKey/value pairs passed to the script
timeoutintegerNoSeconds before call auto‐hangup (default: 300)
curl -X POST https://api.ithinq.ai/v1/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+923001234567",
    "from": "+12223334444",
    "script": "welcome_flow",
    "data": { "firstName": "Ali", "orderId": "123456" },
    "timeout": 180
  }'

GET /v1/status/{callId}

Check the status of a previously initiated call.

Path ParamTypeRequiredDescription
callIdstringYesUnique ID returned from /v1/call
curl -X GET https://api.ithinq.ai/v1/status/abcd1234efgh \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhooks

Configure webhooks to receive real‐time events for call progress, DTMF input, and script completions.

  • Event Types:
    • `call.initiated` — when iThinq AI places the outbound call.
    • `call.answered` — when the recipient answers.
    • `call.dtmf` — when DTMF input is collected.
    • `call.completed` — when the script flow ends or timeout occurs.
  • Payload Example:
    {
      "event": "call.completed",
      "callId": "abcd1234efgh",
      "to": "+923001234567",
      "duration": 120,
      "timestamp": "2025-06-04T07:45:00Z"
    }
  • Securing Webhooks: Validate the `X-ITHINQ-SIG` header on your server. Example (Node.js):
    import crypto from 'crypto';
    
    function verifySignature(req) {
      const secret = process.env.ITHINQ_WEBHOOK_SECRET;
      const payload = req.rawBody; // raw body buffer
      const signature = req.headers['x-ithinq-sig'];
      const computed = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
      return computed === signature;
    }

Code Examples

Ready‐made snippets to help you implement common use cases quickly.

Send SMS via AI Flow (Node.js)

// step1: compose the AI flow with SMS step
const flow = [
  { type: 'say', text: 'Hello, your OTP is {{otp}}.' },
  { type: 'sms', to: '{{to}}', text: 'Your OTP: {{otp}}' }
];

// step2: call the API
const response = await client.call({
  to: '+923001234567',
  from: '+12223334444',
  flow,
  data: { to: '+923001234567', otp: '123456' }
});

console.log('Flow response:', response);

Schedule Recurring Call (Python)

from ithinq_sdk import IthinqClient

client = IthinqClient(api_key='YOUR_API_KEY')

schedule_params = {
  "to": "+923001234567",
  "from_": "+12223334444",
  "script": "reminder_flow",
  "cron": "0 9 * * 1-5",  # Every weekday at 9 AM
  "data": { "name": "Sara" }
}

response = client.schedule_call(schedule_params)
print("Scheduled Job:", response)

FAQs

How do I reset my API key?

In your dashboard, go to “API Keys,” click the “•••” next to the key, and select “Regenerate.” Update your server environment variable with the new key.

Can I use iThinq AI in other countries?

Yes. We support numbers in over 50 countries. See our Pricing page for full coverage details.

Is there a sandbox environment?

Yes. Use the environment variable `ITHINQ_ENV=sandbox` to test calls without incurring charges. All sandbox calls are logged in your dashboard.