curl --request POST \
--url https://api.naturalead.ai/api/conversations/start \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"leadId": 123,
"channel": "whatsapp"
}
'import requests
url = "https://api.naturalead.ai/api/conversations/start"
payload = {
"leadId": 123,
"channel": "whatsapp"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({leadId: 123, channel: 'whatsapp'})
};
fetch('https://api.naturalead.ai/api/conversations/start', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.naturalead.ai/api/conversations/start",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'leadId' => 123,
'channel' => 'whatsapp'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.naturalead.ai/api/conversations/start"
payload := strings.NewReader("{\n \"leadId\": 123,\n \"channel\": \"whatsapp\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.naturalead.ai/api/conversations/start")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"leadId\": 123,\n \"channel\": \"whatsapp\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.naturalead.ai/api/conversations/start")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"leadId\": 123,\n \"channel\": \"whatsapp\"\n}"
response = http.request(request)
puts response.read_body{
"_id": "665f1a2b3c4d5e6f7a8b9c0d",
"leadId": "<string>",
"accountId": "<string>",
"agentConfigId": "<string>",
"channel": "whatsapp",
"leadPhone": "<string>",
"status": "active",
"currentStageIndex": 123,
"messages": [
{
"role": "agent",
"content": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"agentConfigId": "<string>"
}
],
"messageCount": 123,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"campaignId": "<string>",
"leadEmail": "<string>",
"currentStageName": "<string>",
"summary": "<string>",
"qualificationResult": {
"qualified": true,
"reason": "<string>"
}
}{
"error": "<string>"
}{
"error": "<string>"
}Start Conversation
Starts a new LLM-driven conversation with a lead. The system sends the initial outreach message via the specified channel. Requires leads:start_conversation permission.
curl --request POST \
--url https://api.naturalead.ai/api/conversations/start \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"leadId": 123,
"channel": "whatsapp"
}
'import requests
url = "https://api.naturalead.ai/api/conversations/start"
payload = {
"leadId": 123,
"channel": "whatsapp"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({leadId: 123, channel: 'whatsapp'})
};
fetch('https://api.naturalead.ai/api/conversations/start', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.naturalead.ai/api/conversations/start",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'leadId' => 123,
'channel' => 'whatsapp'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.naturalead.ai/api/conversations/start"
payload := strings.NewReader("{\n \"leadId\": 123,\n \"channel\": \"whatsapp\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.naturalead.ai/api/conversations/start")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"leadId\": 123,\n \"channel\": \"whatsapp\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.naturalead.ai/api/conversations/start")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"leadId\": 123,\n \"channel\": \"whatsapp\"\n}"
response = http.request(request)
puts response.read_body{
"_id": "665f1a2b3c4d5e6f7a8b9c0d",
"leadId": "<string>",
"accountId": "<string>",
"agentConfigId": "<string>",
"channel": "whatsapp",
"leadPhone": "<string>",
"status": "active",
"currentStageIndex": 123,
"messages": [
{
"role": "agent",
"content": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"agentConfigId": "<string>"
}
],
"messageCount": 123,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"campaignId": "<string>",
"leadEmail": "<string>",
"currentStageName": "<string>",
"summary": "<string>",
"qualificationResult": {
"qualified": true,
"reason": "<string>"
}
}{
"error": "<string>"
}{
"error": "<string>"
}Authorizations
API key for programmatic access (format nl_live_* or nl_test_*)
Body
Response
Conversation started successfully.
MongoDB ObjectId of the conversation.
"665f1a2b3c4d5e6f7a8b9c0d"
The ID of the associated lead.
MongoDB ObjectId of the account (tenant).
MongoDB ObjectId of the agent configuration used.
The messaging channel used for this conversation.
whatsapp, telegram, email The lead's phone number.
Current status of the conversation.
active, completed, handed_off, dropped Index of the current conversation stage.
Ordered list of messages in the conversation.
Show child attributes
Show child attributes
Total number of messages in the conversation.
When the conversation was created.
When the conversation was last updated. Filter list results with
updatedAfter / updatedBefore for incremental sync.
MongoDB ObjectId of the campaign, if conversation was started by a campaign.
The lead's email address.
Name of the current conversation stage.
Reserved for an LLM-generated prose brief of the conversation.
Not populated today. For structured key points (budget, timeline,
etc.), use GET /api/preferences/{leadId} (Lead Insights) instead.
Deprecated historical scorecard. New completes do not write this field;
prefer currentStageName (terminal stage) as the journey outcome.
Show child attributes
Show child attributes