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.
| Field | Type | Required | Description |
|---|---|---|---|
| to | string | Yes | Destination phone number (+E.164) |
| from | string | Yes | Your verified caller ID |
| script | string | Yes | ID of the conversational script to run |
| data | object | No | Key/value pairs passed to the script |
| timeout | integer | No | Seconds 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 Param | Type | Required | Description |
|---|---|---|---|
| callId | string | Yes | Unique 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.