Ir al contenido
Nuntius

Start Conversation

Ver como Markdown
POST
/public/v1/conversations/start
curl --request POST \
  --url https://api.nuntius.chat/public/v1/conversations/start \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "channelId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "phone": "example", "templateName": "example", "templateLanguage": "example", "variables": [], "leadId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Start (or resume) a 1:1 outbound WhatsApp conversation with an APPROVED template (SPEC_API_PUBLICA.md §2.3) – SAME contract/steps as the internal POST /inbox/ conversations/start-whatsapp (inbox.py::start_whatsapp_conversation, CNV-1 D1), reusing every one of its application-layer collaborators: template approval, channel-identity resolution, active-conversation reuse, the provider send itself. See that function’s own docstring for the full ordering/rollback contract (unchanged here).

channelId foreign/unknown -> 404; not a connected WhatsApp channel -> 422. (templateName, templateLanguage) not an APPROVED template of THIS tenant -> 422 (CampaignTemplateNotApprovedError). leadId, when given, foreign/unknown -> 404, resolved BEFORE any write/send. The resulting (or reused) conversation is assigned to the KEY OWNER (PublicStartConversationRequest’s own docstring), never anything the body could override.

Idempotency-Key (API-3, D-API-4) is optional: a repeat with the SAME header and SAME body replays the original response without sending a second WhatsApp template; the SAME header with a DIFFERENT body -> 422 IDEMPOTENCY_KEY_REUSE_MISMATCH.

Permiso necesario: tenant:conversations.manage

Authorizations

Sección titulada «Authorizations»

Request Bodyrequired

Sección titulada «Request Bodyrequired»
Media typeapplication/json
PublicStartConversationRequest

POST /public/v1/conversations/start body – SAME contract as the internal StartWhatsAppConversationRequest (POST /inbox/conversations/start-whatsapp, SPEC_API_PUBLICA.md §2.3): starts (or resumes) a 1:1 outbound WhatsApp conversation with an APPROVED template.

There is deliberately NO assignment field – the resulting conversation is always assigned to the KEY OWNER (the real user behind the calling API key), never anything the client could send, same “la atiende quien la inicia” rule the internal endpoint enforces.

object
channelId
required
Channelid
string format: uuid
phone
required
Phone
string
templateName
required
Templatename
string
templateLanguage
required
Templatelanguage
string
variables
Variables
Array<string>
default:
leadId
Any of:
string format: uuid

Responses

Sección titulada «Responses»

201

Sección titulada «201»

Successful Response

Media typeapplication/json
PublicConversationOut

A single conversation, curated subset of the internal ConversationOut.

Drops channelName/mode/sentiment/quality/unreadCount – operator-console presentation/workflow state, not part of the curated read surface (SPEC_API_PUBLICA.md §2.3’s own “Excluido” list: workflow state is deliberately withheld from third parties). status is the RAW Conversation.status domain value ('active'/'escalated'/'resolved'), never the internal _map_status UI collapse to 'open' – see ConversationFilters’s own docstring for why this NEW, independently-versioned contract does not inherit that Platform presentation concern.

object
id
required
Id
string
channel
required
Channel
string
channelId
Any of:
string
status
required
Status
string
subject
Any of:
string
customer
required
PublicConversationCustomerOut

Curated customer block for a public conversation – a narrower shape than the internal CustomerOut (schemas/inbox.py): drops avatarUrl (never populated by any real path in this codebase) and authSessionActive (AC-4, an operator-console-only signal about a LIVE Redis session – meaningless to an M2M integration polling this endpoint asynchronously).

object
id
required
Id
string
name
Any of:
string
email
Any of:
string
phone
Any of:
string
customerId
Any of:
string
assignedOperatorId
Any of:
string
lastMessagePreview
required
Lastmessagepreview
string
lastMessageAt
required
Lastmessageat
string
createdAt
required
Createdat
string

Examplegenerated

{
  "id": "example",
  "channel": "example",
  "channelId": "example",
  "status": "example",
  "subject": "example",
  "customer": {
    "id": "example",
    "name": "example",
    "email": "example",
    "phone": "example",
    "customerId": "example"
  },
  "assignedOperatorId": "example",
  "lastMessagePreview": "example",
  "lastMessageAt": "example",
  "createdAt": "example"
}

422

Sección titulada «422»

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object

Examplegenerated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}