Documentación
superleads.mx
Documentación › Referencia de la API › Conversations

Conversations

Referencia de la API · ☕ 19 min de lectura
Actualizado el 19 Jun 2026

Conversations API

Documentación de la API de Conversations

Servidor base: https://services.leadconnectorhq.com

Endpoints

GET /conversations/search

Buscar conversaciones Returns a list of all conversations matching the search criteria along with the sort and filter options selected.

Scopes requeridos: conversations.readonly

Parametros: - Versión (header, string) (requerido) — Versión de la API - locationId (query, string) (requerido) — Id de sede - contactId (query, string) — Id de contacto - assignedTo (query, string) — User IDs that conversations are assigned to. Multiple IDs can be provided as comma-separated values. Use "unassigned" to fetch conversations not assigned to any user. - followers (query, string) — User IDs of followers to filter conversations by. Multiple IDs can be provided as comma-separated values. - mentions (query, string) — User Id of the mention. Multiple values are comma separated. - query (query, string) — Search paramater as a string - sort (query, string) — Sort paramater - asc or desc - startAfterDate (query, any) — Search to begin after the specified date - should contain the sort value of the last document - id (query, string) — Id of the conversation - limit (query, number) — Limit of conversations - Default is 20 - lastMessageType (query, string) — Type of the last message in the conversation as a string - lastMessageAction (query, string) — Action of the last outbound message in the conversation as string. - lastMessageDirection (query, string) — Direction of the last message in the conversation as string. - status (query, string) — The status of the conversation to be filtered - all, read, unread, starred - sortBy (query, string) — The sorting of the conversation to be filtered as - manual messages or all messages - sortScoreProfile (query, string) — Id of score profile on which sortBy.ScoreProfile should sort on - scoreProfile (query, string) — Id of score profile on which conversations should get filtered out, works with scoreProfileMin & scoreProfileMax - scoreProfileMin (query, number) — Minimum value for score - scoreProfileMax (query, number) — Maximum value for score - startDate (query, number) — Start date filter for dateAdded field (Unix timestamp in milliseconds) - endDate (query, number) — End date filter for dateAdded field (Unix timestamp in milliseconds)

Respuestas: - 200 — Successfully fetched the conversations - 400 — Peticion invalida - 401 — No autorizado

GET /conversations/{conversationId}

Obtener conversacion Get the conversation details based on the conversation Id

Scopes requeridos: conversations.readonly

Parametros: - Versión (header, string) (requerido) — Versión de la API - conversationId (path, string) (requerido) — Conversation Id as string

Respuestas: - 200 — Respuesta exitosa - 400 — Peticion invalida - 401 — No autorizado

PUT /conversations/{conversationId}

Actualizar conversacion Update the conversation details based on the conversation Id

Scopes requeridos: conversations.write

Parametros: - Versión (header, string) (requerido) — Versión de la API - conversationId (path, string) (requerido) — Conversation Id as string

Cuerpo de la peticion (application/json): - locationId (requerido) — string — Location Id as string - unreadCount — number — Count of unread messages in the conversation - starred — boolean — Starred status of the conversation. - feedback — string — Live chat feedback value for the conversation

Respuestas: - 200 — Respuesta exitosa - 400 — Peticion invalida - 401 — No autorizado

DELETE /conversations/{conversationId}

Eliminar conversacion Delete the conversation details based on the conversation Id

Scopes requeridos: conversations.write

Parametros: - Versión (header, string) (requerido) — Versión de la API - conversationId (path, string) (requerido) — Conversation Id as string

Respuestas: - 200 — Respuesta exitosa - 400 — Peticion invalida - 401 — No autorizado

GET /conversations/messages/email/{id}

Obtener email by Id Scopes requeridos: conversations/message.readonly

Respuestas: - 200 — Email object for the id given.

DELETE /conversations/messages/email/{emailMessageId}/schedule

Cancelar a scheduled email message. Post the messageId for the API to delete a scheduled email message.

Scopes requeridos: conversations/message.write

Parametros: - emailMessageId (path, string) (requerido) — Id de Email Message

Respuestas: - 200 — The scheduled email message was cancelled successfully

PUT /conversations/messages/email/{id}/status

Actualizar email message status Update delivery events, per-recipient statuses, and the overall message status for an email sent via a custom conversation provider.

Authorization

  • Requires the conversations/message.write OAuth scope.
  • The calling OAuth app must own the conversation provider that originally sent the email.
  • Attempts to update emails sent via LC Email or Mailgun will return 403 Forbidden.

Updatable Fields

status is required on every request. You may also include events and/or recipients.

events — Aggregate delivery event counters (integers). Counters are merged into the existing values (not replaced). Setting a counter to 0 is treated as no-op and will not reset the stored value.

recipients — Per-recipient delivery statuses. Each entry maps a recipient email address to a MessageStatus value. Use failReason to capture bounce or rejection details when the status is failed.

status — The overall message status. Accepts any MessageStatus enum value.

Event Inference

The API automatically infers related events to maintain data consistency: - clicked, complained, unsubscribed, or replied → implies opened (set to 1 if not already provided and open tracking is enabled) and delivered (set to 1). - opened → implies delivered (set to 1 if not provided). - delivered, permanent_fail, or temporary_fail → implies accepted (set to 1 if not provided).

Timestamps

The API automatically records server-side timestamps on first occurrence for delivered, opened, and clicked events. Subsequent updates to these counters do not overwrite the original timestamp.

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API - id (path, string) (requerido) — Id de Email message

Cuerpo de la peticion (application/json): - events — — Aggregate delivery event counters. Counters are merged into existing values. The API automatically infers related events (e.g., reporting clicked will also set opened and delivered if not already present). See the endpoint description for the full inference rules. - recipients — array — Per-recipient delivery statuses. Each entry maps a recipient email address to a delivery status. Entries are upserted — if a recipient already has a status, it will be overwritten with the new value. - emailId (requerido) — string — The recipient's email address. This is used as the key to store and update the per-recipient status. Must match one of the original recipients of the email. - status (requerido) — string — The delivery status for this specific recipient. Common values for status updates: delivered (successfully delivered), failed (delivery failed — provide failReason), opened (recipient opened the email), clicked (recipient clicked a link). - failReason — string — Human-readable reason for the delivery failure. Only applicable when status is failed. Examples: "Mailbox not found", "Quota exceeded", "Blocked by recipient server". - status (requerido) — string — The overall status of the email message. Required on every request. For emails with multiple recipients, consider using the recipients array for granular tracking and this field for the aggregate status.

Respuestas: - 200 — Email message status updated successfully - 400 — Peticion invalida - 401 — No autorizado - 403 — Forbidden - status updates are only supported for custom conversation provider emails

GET /conversations/messages/export

Exportar messages by location Id Export messages for a specific location with cursor-based pagination support. Response includes messageType (string), source, and subType fields. The channel parameter is optional - if not provided, all non-email message types will be returned including activity messages (opportunity updates, appointments, etc.).

Scopes requeridos: conversations/message.readonly

Parametros: - Versión (header, string) (requerido) — Versión de la API - locationId (query, string) (requerido) — Location Id to filter messages by - limit (query, number) — Number of messages to return per page - cursor (query, string) — Cursor for pagination. Pass the nextCursor from previous response to get next page. - sortBy (query, string) — Field to sort by - sortOrder (query, string) — Sort order - conversationId (query, string) — Id de Filter messages by conversation - contactId (query, string) — Id de Filter messages by contact - channel (query, string) — Filter by message channel. Optional - when not provided, all non-email message types will be returned including activity messages (opportunity updates, appointments, etc.). To fetch email messages, you must explicitly set channel=Email. - startDate (query, string) — Start date to filter messages by - endDate (query, string) — End date to filter messages by

Respuestas: - 200 — List of messages for the location with pagination details. - 400 — Peticion invalida - 401 — No autorizado

GET /conversations/messages/{id}

Obtener message by message id Get message by message id.

Scopes requeridos: conversations/message.readonly

Parametros: - Versión (header, string) (requerido) — Versión de la API

Respuestas: - 200 — Message object for the id given. - 400 — Peticion invalida - 401 — No autorizado

GET /conversations/{conversationId}/messages

Obtener messages by conversation id Get messages by conversation id.

Scopes requeridos: conversations/message.readonly

Parametros: - Versión (header, string) (requerido) — Versión de la API - conversationId (path, string) (requerido) — Conversation Id as string - lastMessageId (query, string) — Message Id of the last message in the list as a string - limit (query, number) — Number of messages to be fetched from the conversation. Default limit is 20 - type (query, string) — Types of message to fetched separated with comma

Respuestas: - 200 — List of messages for the conversation id of the given type. - 400 — Peticion invalida - 401 — No autorizado

POST /conversations/messages

Enviar a new message Post the necessary fields for the API to send a new message.

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API

Cuerpo de la peticion (application/json): - type (requerido) — string — Type of message being sent - subType (requerido) — object — Type of message being sent - contactId (requerido) — string — Id of the contact receiving the message - appointmentId — string — Id of the associated appointment - attachments — array — Array of attachment URLs - emailFrom — string — Email address to send from - emailCc — array — Array of CC email addresses - emailBcc — array — Array of BCC email addresses - html — string — HTML content of the message - message — string — Text content of the message - subject — string — Subject line for email messages - replyMessageId — string — Id of message being replied to - templateId — string — Id of message template - threadId — string — Id of message thread. For email messages, this is the message Id that contains multiple email messages in the thread - scheduledTimestamp — number — UTC Timestamp (in seconds) at which the message should be scheduled - conversationProviderId — string — Id of conversation provider - emailTo — string — Email address to send to, if different from contact's primary email. This should be a valid email address associated with the contact. - customSubtypeId — string — Custom subtype Id for email unsubscription preferences. Only applies to email messages. - emailReplyMode — string — Mode for email replies - fromNumber — string — Phone number used as the sender number for outbound messages - toNumber — string — Recipient phone number for outbound messages - forward — — Forwarding configuration for emails - status (requerido) — string — Message status - usesNativeSchedulingAi — boolean — Whether the scheduled email uses native AI for the email scheduling - optimizationPeriod — string — Optimization period in hours (24h, 48h, or 72h)

Respuestas: - 200 — Created the message - 400 — Peticion invalida - 401 — No autorizado

POST /conversations/messages/inbound

Agregar an inbound message Post the necessary fields for the API to add a new inbound message.

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API

Cuerpo de la peticion (application/json): - type (requerido) — string — Message Type - attachments — array — Array of attachments - message — string — Message Body - conversationId (requerido) — string — Conversation Id - contactId (requerido) — string — Contact Id - conversationProviderId (requerido) — string — Conversation Provider Id - html — string — HTML Body of Email - subject — string — Subject of the Email - emailFrom — string — Email address to send from. This field is associated with the contact record and cannot be dynamically changed. - emailTo — string — Recipient email address. This field is associated with the contact record and cannot be dynamically changed. - emailCc — array — List of email address to CC - emailBcc — array — List of email address to BCC - emailMessageId — string — Send the email message id for which this email should be threaded. This is for replying to a specific email - altId — string — external mail provider's message id - direction — object — Message direction, if required can be set manually, default is outbound - date — string — Date of the inbound message - call — — Phone call dialer and receiver information

Respuestas: - 200 — Created the message - 400 — Peticion invalida - 401 — No autorizado

POST /conversations/messages/outbound

Agregar an external outbound call Post the necessary fields for the API to add a new outbound call.

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API

Cuerpo de la peticion (application/json): - type (requerido) — string — Message Type - attachments — array — Array of attachments - conversationId (requerido) — string — Conversation Id - conversationProviderId (requerido) — string — Conversation Provider Id - altId — string — external mail provider's message id - date — string — Date of the outbound message - call — — Phone call dialer and receiver information

Respuestas: - 200 — Created the message - 400 — Peticion invalida - 401 — No autorizado

DELETE /conversations/messages/{messageId}/schedule

Cancelar a scheduled message. Post the messageId for the API to delete a scheduled message.

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API - messageId (path, string) (requerido) — Id de mensaje

Respuestas: - 200 — The scheduled message was cancelled successfully - 400 — Peticion invalida - 401 — No autorizado

POST /conversations/messages/upload

Upload file attachments Post the necessary fields for the API to upload files. The files need to be a buffer with the key "fileAttachment".

The allowed file types are:

  • JPG
  • JPEG
  • PNG
  • MP4
  • MPEG
  • ZIP
  • RAR
  • PDF
  • DOC
  • DOCX
  • TXT
  • MP3
  • WAV


The API will return an object with the URLs

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API

Cuerpo de la peticion (multipart/form-data): - conversationId (requerido) — string — Conversation Id - contactId (requerido) — string — Contact Id - locationId (requerido) — string — Location Id associated with the upload request - attachmentUrls (requerido) — array — Array of attachment URLs to upload for the conversation - chatServiceSid — string — Twilio chat service SID for group SMS uploads - isGroupSms — string — Flag to indicate group SMS upload flow. When true, only 1 file upload is allowed per request.

Respuestas: - 200 — Uploaded the file successfully - 400 — Peticion invalida - 401 — No autorizado - 413 — Payload Too Large - 415 — Unsupported Media Type

PUT /conversations/messages/{messageId}/status

Actualizar message status Post the necessary fields for the API to update message status.

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API - messageId (path, string) (requerido) — Id de mensaje

Cuerpo de la peticion (application/json): - status (requerido) — string — Message status - error — — Error object from the conversation provider - emailMessageId — string — Email message Id - recipients — array — Email delivery status for additional email recipients.

Respuestas: - 200 — Created the message - 400 — Peticion invalida - 401 — No autorizado

PUT /conversations/messages/{messageId}/attachments

Agregar message attachments Set attachments on an existing message (replaces existing). Maximum 5 URLs. Supported for TYPE_CUSTOM_CALL (34) and TYPE_CALL (1) with subType EXTERNAL_CALL.

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API - messageId (path, string) (requerido) — Id de mensaje

Cuerpo de la peticion (application/json): - attachments (requerido) — array — Array of attachment URLs to set on the message (replaces existing). Maximum 5 URLs.

Respuestas: - 200 — Successfully set message attachments - 400 — Peticion invalida - 401 — No autorizado - 403 — Message type does not support attachment updates - 404 — Message not found

GET /conversations/messages/{messageId}/locations/{locationId}/recording

Obtener Recording by Message Id Get the recording for a message by passing the message id

Scopes requeridos: conversations/message.readonly, conversations/message.readonly

Parametros: - Versión (header, string) (requerido) — Versión de la API - locationId (path, string) (requerido) — Location Id as string - messageId (path, string) (requerido) — Message Id as string

Respuestas: - 200 — Gives the attached recording to the message - 400 — Peticion invalida - 401 — No autorizado

GET /conversations/locations/{locationId}/messages/{messageId}/transcription

Obtener transcription by Message Id Get the recording transcription for a message by passing the message id

Scopes requeridos: conversations/message.readonly, conversations/message.readonly

Parametros: - Versión (header, string) (requerido) — Versión de la API - locationId (path, string) (requerido) — Location Id as string - messageId (path, string) (requerido) — Message Id as string

Respuestas: - 200 — Gives the attached recording transcription to the message - 400 — Peticion invalida - 401 — No autorizado

GET /conversations/locations/{locationId}/messages/{messageId}/transcription/download

Download transcription by Message Id Download the recording transcription for a message by passing the message id

Scopes requeridos: conversations/message.readonly, conversations/message.readonly

Parametros: - Versión (header, string) (requerido) — Versión de la API - locationId (path, string) (requerido) — Location Id as string - messageId (path, string) (requerido) — Message Id as string

Respuestas: - 200 — Downloads the attached transcription of the message - 400 — Peticion invalida - 401 — No autorizado

POST /conversations/providers/live-chat/typing

Agent/Ai-Bot is typing a message indicator for live chat Agent/AI-Bot will call this when they are typing a message in live chat message

Scopes requeridos: conversations/livechat.write

Parametros: - Versión (header, string) (requerido) — Versión de la API

Cuerpo de la peticion (application/json): - locationId (requerido) — string — Location Id - isTyping (requerido) — string — Typing status - visitorId (requerido) — string — Unique Id assigned to each live chat visitor. - conversationId (requerido) — string — Conversation Id

Respuestas: - 201 — Show typing indicator for live chat - 400 — Peticion invalida - 401 — No autorizado - 422 — Entidad no procesable

POST /conversations/

Crear conversacion Creates a new conversation with the data provided

Scopes requeridos: conversations.write

Parametros: - Versión (header, string) (requerido) — Versión de la API

Cuerpo de la peticion (application/json): - locationId (requerido) — string — Location Id as string - contactId (requerido) — string — Contact Id as string

Respuestas: - 201 — Respuesta exitosa - 400 — Peticion invalida - 401 — No autorizado

POST /conversations/messages/review-reply

Enviar a review reply to Google My Business Post a reply to a customer review on Google My Business

This endpoint is internal-only and is not supported for OAuth or public API integrations. It will be removed from the public OpenAPI specification in a future release.

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API

Cuerpo de la peticion (application/json): - conversationId (requerido) — string — Conversation Id (must have reviewId) - locationId (requerido) — string — Location Id - message (requerido) — string — Review reply message text

Respuestas: - 200 — Review reply sent successfully - 400 — Peticion invalida - 401 — No autorizado

POST /conversations/messages/upload/initiate

Initiate file upload to GCS Generates a signed URL for direct file upload to Google Cloud Storage. Returns a signed URL valid for 15 minutes. Upload file via PUT request, then call /complete to finalize.

This endpoint is internal-only and is not supported for OAuth or public API integrations. It will be removed from the public OpenAPI specification in a future release.

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API

Cuerpo de la peticion (application/json): - locationId (requerido) — string — Location Id - conversationId (requerido) — string — Conversation Id - filename (requerido) — string — Original filename with extensión - contentType (requerido) — string — MIME type of the file - fileSize — number — File size in bytes (optional, for pre-validation) - channel (requerido) — string — Channel type for size limits (WHATSAPP for 100MB limit, others for 5MB)

Respuestas: - 200 — Signed URL generated successfully - 400 — Bad Request - Invalid parameters - 401 — No autorizado - 413 — File size exceeds maximum allowed limit

POST /conversations/messages/upload/complete

Complete file upload Validates the uploaded file in GCS and returns the public URL. Call this endpoint after successfully uploading the file to the signed URL.

This endpoint is internal-only and is not supported for OAuth or public API integrations. It will be removed from the public OpenAPI specification in a future release.

Scopes requeridos: conversations/message.write

Parametros: - Versión (header, string) (requerido) — Versión de la API

Cuerpo de la peticion (application/json): - uploadId (requerido) — string — Upload Id from request response - filePath (requerido) — string — File path from request response - locationId (requerido) — string — Location Id - conversationId (requerido) — string — Conversation Id - filename (requerido) — string — Original filename (for response mapping)

Respuestas: - 200 — Upload completed successfully - 400 — Bad Request - Invalid parameters - 401 — No autorizado - 404 — File not found in storage - upload may have failed or URL expired

Enter para abrir el primer resultado · Esc para cerrar