API reference
Messaging
Send WhatsApp, SMS and email through the channels connected to the workspace, and read the conversations your team has with customers.
Send a message to a record
POST
/conversations/records/{recordId}/sendSends a message to the phone number or email address on a record. A conversation is opened, or the existing one is continued, and the message appears on the record's timeline.
Path parameters
recordIduuidrequiredThe lead, contact or other record to message.
Body
providerstringrequiredThe kind of channel:
whatsapp, sms, email, messenger or instagram.textstringThe message. Required unless you send a template.
subjectstringEmail subject.
templateobjectAn approved WhatsApp template:
{"name":"order_ready","language":"en","params":["Aisha"]}. Needed to start a WhatsApp conversation outside the 24-hour window.channelIduuidWhich channel to send from, when more than one of that kind is connected.
- The response is the message that was sent. Its
conversationIdis the conversation it belongs to. - Returns
404with the reason when the record has no phone number or email address, or when no channel of that kind is connected.
Request
curl -X POST "https://api.spartivo.com/api/v1/conversations/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d/send" \
-H "Authorization: Bearer wk_your_key" \
-H "Content-Type: application/json" \
-d '{"provider":"whatsapp","template":{"name":"order_ready","language":"en","params":["Aisha"]}}'Response
{
"id": "183533ac-9fc3-492b-97ea-a45fe8709817",
"conversationId": "d142ba9c-9443-4d99-8806-b81c335c5c49",
"direction": "outbound",
"senderUserId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
"subject": null,
"text": null,
"media": [],
"template": {
"name": "order_ready",
"language": "en",
"params": [
"Aisha"
]
},
"status": "sent",
"internalNote": false,
"error": null,
"createdAt": "2026-11-18T08:37:06.002Z"
}Reply in a conversation
POST
/conversations/replySends a reply in an existing conversation, or adds an internal note that the customer does not see.
Body
conversationIduuidrequiredThe conversation.
textstringThe message.
mediaobject[]Attachments:
[{"url":"file:<file id>","mimeType":"application/pdf","name":"quote.pdf"}]. Upload the file first with Upload a file.internalNotebooleantrue to add a note for the team instead of sending.subjectstringEmail subject.
Request
curl -X POST "https://api.spartivo.com/api/v1/conversations/reply" \
-H "Authorization: Bearer wk_your_key" \
-H "Content-Type: application/json" \
-d '{"conversationId":"d142ba9c-9443-4d99-8806-b81c335c5c49","text":"Your quote is attached.","media":[{"url":"file:dacced18-8a22-4702-819f-abf6390f57ff","mimeType":"application/pdf","name":"quote.pdf"}]}'Response
{
"id": "183533ac-9fc3-492b-97ea-a45fe8709817",
"conversationId": "d142ba9c-9443-4d99-8806-b81c335c5c49",
"direction": "outbound",
"senderUserId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
"subject": null,
"text": "Your quote is attached.",
"media": [
{
"url": "…",
"mimeType": "application/pdf",
"name": "quote.pdf"
}
],
"template": null,
"status": "sent",
"internalNote": false,
"error": null,
"createdAt": "2026-11-18T08:37:06.002Z"
}List conversations
GET
/conversationsConversations in the shared inbox, most recent first.
Query parameters
statusstringopen, pending, snoozed or closed.assigneeIduuidKeep one person's conversations.
minestring1 to keep conversations assigned to the key's user.unassignedstring1 to keep conversations nobody has picked up.channelIduuidKeep one channel's conversations.
qstringSearch by customer name, phone number or email address, or message text.
Request
curl "https://api.spartivo.com/api/v1/conversations?status=open" \
-H "Authorization: Bearer wk_your_key"Response
[
{
"id": "d142ba9c-9443-4d99-8806-b81c335c5c49",
"channelId": "0496ef56-9d30-4e0c-85b6-33cbdc3ec076",
"recordId": "348956d9-c7c8-49c5-b08f-da6fb8d7f66f",
"assigneeId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
"status": "open",
"unreadCount": 1,
"lastMessageAt": "2026-11-17T09:21:29.171Z",
"lastInboundAt": "2026-11-17T09:18:28.301Z",
"channel": {
"id": "0496ef56-9d30-4e0c-85b6-33cbdc3ec076",
"provider": "whatsapp",
"name": "Sales WhatsApp"
},
"record": {
"id": "348956d9-c7c8-49c5-b08f-da6fb8d7f66f",
"name": "Layla Hassan"
}
}
]Get a conversation
GET
/conversations/{id}One conversation with its messages.
Path parameters
iduuidrequiredThe conversation id.
- Reading a conversation marks it as read for the team. Add
?peek=1to leave the unread count alone.
Request
curl "https://api.spartivo.com/api/v1/conversations/d142ba9c-9443-4d99-8806-b81c335c5c49" \
-H "Authorization: Bearer wk_your_key"Response
{
"id": "d142ba9c-9443-4d99-8806-b81c335c5c49",
"status": "open",
"recordId": "348956d9-c7c8-49c5-b08f-da6fb8d7f66f",
"assigneeId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
"messages": [
{
"id": "5b1f0c1e-2f37-4d7c-9b65-0a4f4c0e6a11",
"conversationId": "d142ba9c-9443-4d99-8806-b81c335c5c49",
"direction": "inbound",
"text": "Is my order ready?",
"media": [],
"status": "delivered",
"internalNote": false,
"createdAt": "2026-11-17T09:18:28.301Z"
}
]
}