SpartivoDocs
Open app
Get started
OverviewQuickstartAuthenticationRequests and errors
API reference
RecordsModules and fieldsFilesMessagingDocuments and e-signatureFunctionsWebhooks
Spartivo Script
IntroductionLanguage guideCRM and actionsBuilt-in functionsExamples
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}/send

Sends 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
recordIduuidrequired
The lead, contact or other record to message.
Body
providerstringrequired
The kind of channel: whatsapp, sms, email, messenger or instagram.
textstring
The message. Required unless you send a template.
subjectstring
Email subject.
templateobject
An approved WhatsApp template: {"name":"order_ready","language":"en","params":["Aisha"]}. Needed to start a WhatsApp conversation outside the 24-hour window.
channelIduuid
Which channel to send from, when more than one of that kind is connected.
  • The response is the message that was sent. Its conversationId is the conversation it belongs to.
  • Returns 404 with 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/reply

Sends a reply in an existing conversation, or adds an internal note that the customer does not see.

Body
conversationIduuidrequired
The conversation.
textstring
The message.
mediaobject[]
Attachments: [{"url":"file:<file id>","mimeType":"application/pdf","name":"quote.pdf"}]. Upload the file first with Upload a file.
internalNoteboolean
true to add a note for the team instead of sending.
subjectstring
Email 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/conversations

Conversations in the shared inbox, most recent first.

Query parameters
statusstring
open, pending, snoozed or closed.
assigneeIduuid
Keep one person's conversations.
minestring
1 to keep conversations assigned to the key's user.
unassignedstring
1 to keep conversations nobody has picked up.
channelIduuid
Keep one channel's conversations.
qstring
Search 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
iduuidrequired
The conversation id.
  • Reading a conversation marks it as read for the team. Add ?peek=1 to 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"
    }
  ]
}
Previous← FilesNextDocuments and e-signature →
On this page
POSTSend a message to a recordPOSTReply in a conversationGETList conversationsGETGet a conversation