The Problem: Market Research is Still Painfully Manual
Picture this: you need to survey 50 local suppliers about delivery times, prices, and capacity. The traditional approach?
- Export a list of phone numbers
- Open WhatsApp one by one
- Send the same message 50 times
- Wait for replies, copy answers into a spreadsheet
- Follow up with the next question manually
- Repeat for every question
This is a data collection nightmare — and it hasn't changed much in years. Even with WhatsApp Business, automating a multi-step questionnaire requires building your own bot, managing conversation state, handling webhooks, and formatting the final report.
What if you could do all of that with a single API call?
The Solution: POST /whatsapp/research
IteraTools now has a dedicated market research endpoint. You provide a list of phone numbers and a list of questions — the API handles everything else:
- Sends each contact the initial greeting
- Asks the first question
- Captures their reply
- Sends the next question automatically
- Generates a structured report when everyone's done
No webhook setup. No conversation state management. No spreadsheet assembly.
The 4 Endpoints
1. POST /whatsapp/research/start — Launch the research
curl -X POST https://api.iteratools.com/whatsapp/research/start \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"numbers": [
"+5548991234567",
"+5511987654321",
"+5521998765432"
],
"questions": [
"Qual seu prazo médio de entrega?",
"Qual o preço médio por unidade?",
"Vocês atendem pessoa jurídica?",
"Quantas unidades vocês conseguem entregar por semana?"
]
}'
Response:
{
"ok": true,
"research_id": "res_abc123def456",
"total_contacts": 3,
"messages_sent": 3,
"status": "started"
}
Each contact receives: "Olá! Gostaríamos de fazer algumas perguntas rápidas. Pode nos ajudar?" followed by question #1.
Price: $0.070 per contact (covers the WhatsApp conversation initiation cost).
2. GET /whatsapp/research/:id — Track progress
curl https://api.iteratools.com/whatsapp/research/res_abc123def456 \
-H "Authorization: Bearer YOUR_API_KEY"
Response:
{
"ok": true,
"research_id": "res_abc123def456",
"status": "in_progress",
"total": 3,
"responded": 1,
"pending": 2,
"contacts": [
{ "number": "+5548991234567", "status": "done", "current_question": 4, "answers_count": 4 },
{ "number": "+5511987654321", "status": "in_progress", "current_question": 2, "answers_count": 2 },
{ "number": "+5521998765432", "status": "contacted", "current_question": 0, "answers_count": 0 }
]
}
Price: $0.001
3. POST /whatsapp/research/:id/answer — Internal webhook (auto-called)
This endpoint powers the "auto-advance" behavior. When a contact replies to a WhatsApp message, the webhook receives the message and calls this endpoint internally:
curl -X POST https://api.iteratools.com/whatsapp/research/res_abc123/answer \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"number": "+5548991234567",
"answer": "3 dias úteis"
}'
Response:
{
"ok": true,
"status": "in_progress",
"next_question": "Qual o preço médio por unidade?",
"answers_recorded": 1
}
When all questions are answered:
{
"ok": true,
"status": "done",
"answers_recorded": 4
}
The contact also receives: "Obrigado pelas respostas! Isso nos ajudará muito. 🙏"
Price: $0.001
4. GET /whatsapp/research/:id/report — Get the structured report
curl https://api.iteratools.com/whatsapp/research/res_abc123def456/report \
-H "Authorization: Bearer YOUR_API_KEY"
Response:
{
"ok": true,
"research_id": "res_abc123def456",
"status": "completed",
"completed_at": "2026-03-19T17:30:00Z",
"summary": {
"total": 3,
"responded": 3,
"pending": 0,
"completion_rate": "100%"
},
"responses": [
{
"number": "+5548991234567",
"answers": [
{ "question": "Qual seu prazo médio de entrega?", "answer": "3 dias úteis" },
{ "question": "Qual o preço médio por unidade?", "answer": "R$ 25,00" },
{ "question": "Vocês atendem pessoa jurídica?", "answer": "Sim, com nota fiscal" },
{ "question": "Quantas unidades vocês conseguem entregar por semana?", "answer": "Até 500 unidades" }
]
}
]
}
Price: $0.001
Use Cases
Price discovery
Survey 20 local suppliers for the same product. Get back a structured table of prices, MOQs, and lead times — without writing a line of scraping code.
Supplier qualification
Ask questions about certifications, capacity, location, and payment terms. Filter and rank based on responses.
Customer satisfaction (NPS)
Send a 3-question survey to recent customers via WhatsApp (highest open rate of any channel).
Availability checks
"Can you deliver X units by date Y?" — Run this against 10 vendors in parallel. Get answers in your app.
Competitive intelligence
Survey distributors or retailers about competitor pricing and stock levels.
How it works under the hood
The API stores each research session in SQLite with two tables:
-
wa_research— session metadata (questions, status, api_key) -
wa_research_contacts— per-contact state (current_question, answers JSON array)
When a WhatsApp reply comes in via the Meta Cloud API webhook, the system looks up any active research session for that phone number and automatically calls the /answer endpoint internally. This advances the conversation without any client-side logic.
Pricing Summary
| Endpoint | Price |
|---|---|
| POST /whatsapp/research/start | $0.070 / contact |
| GET /whatsapp/research/:id | $0.001 |
| POST /whatsapp/research/:id/answer | $0.001 |
| GET /whatsapp/research/:id/report | $0.001 |
For 10 contacts + 1 status check + 1 report: $0.702 total.
Compare that to a market research firm charging $5–$20 per completed survey.
AI Agent Integration (MCP)
The endpoint is also available as an MCP tool (whatsapp_research_start, whatsapp_research_status, whatsapp_research_report) via the iteratools-mcp npm package:
npx -y iteratools-mcp
This lets AI agents like Claude, GPT-4o, or Cursor use the research tools directly — no API client needed.
Get Started
- API: api.iteratools.com
- Docs: iteratools.com/docs
- Tool page: iteratools.com/tools/whatsapp-research
The API uses x402 micropayments on Base (USDC) — you pay per call, no subscription required. Or use a Bearer API key for higher volume.
Questions? Open an issue or reach out via the docs page.
Top comments (0)