NUACOM API

Messaging

Conversations

Conversations is the messaging module: one thread per contact and channel, with the same message, participant and delivery-status shapes for SMS (channel_type 1), WhatsApp (2) and MMS (3). This guide covers the thread endpoints, delivery statuses, assignment rules, webhooks and prices. What each channel needs before you can send is in its own guide: Conversations / SMS (credit, sender names, templates, MMS, the legacy history endpoints) and Conversations / WhatsApp (sender, templates, media, the 24-hour window). Forwarding inbound SMS to email is configured in the portal (Settings → SMS).

Vocabulary

  • A conversation has an id (UUID), a channel_type, the sender_id it is sent from (your sender name or number), participants (participant_type phone_number, email or user; participant_id; is_system_user for your own users), is_group, assigned_to_id / assigned_department_id, is_pinned, is_active (false once archived), unread_count, last_message_at and, for WhatsApp, expires_at (the end of the 24-hour reply window). channels lists every channel the same contact has written on.
  • A message has direction (inbound / outbound), message_type (0 text, 5 image, 6 video, 7 file, 8 location, 9 audio, 10 sticker, 11 contact), content, content_url, attachments (one entry per media file with content_url, thumbnail_url, mime_type, file_size), metadata (template_id and template_variables for a template, location, media, and media_error when an inbound file could not be fetched), scheduled_for, is_draft and statuses: one row per recipient with status (0 pending, 1 sent, 2 delivered, 3 read, 4 failed, 5 scheduled), error_code, error_description.

Workflow (what the portal does)

  1. The inbox: GET /v2/conversations lists the account's threads, newest activity first. Filters: search (number, name or text), channel (1, 2 or 3), from_date / to_date (Y-m-d, the portal defaults to the last 31 days), status (last message status, 0–5), assigned_to_id, is_active (0 to include archived threads), is_group, unread=1, unassigned=1, expires_in_hours (WhatsApp windows closing soon; the last three drop pagination and return up to 500 rows), sorts (comma-separated, - for descending, for example is_pinned,-last_message_at), page, per_page (default 15). The response is paginated: data, total, per_page, current_page, last_page, from, to. GET /v2/conversations/unread-count is the badge counter.
  2. Open a thread: GET /v2/conversations/{conversation} returns the conversation with participants and its non-draft messages in chronological order, and marks it read for the calling user. WhatsApp messages are included only when the account has the WhatsApp feature.
  3. Reply: POST /v2/conversations/{conversation}/messages with content, or media as content_url / content_file (WhatsApp) or media_ids (MMS), or a template as metadata.template_id plus metadata.template_variables. Optional scheduled_for, is_draft, opt_in / opt_out (SMS), and channel_type to pick the channel on a thread that has both SMS and WhatsApp. Answers 201 with the message; an archived thread is restored. 402 means no credit, 400 carries the domain code of a failed send (see the SMS guide), 422 a validation failure or a closed WhatsApp window.
  4. Start a thread: POST /v2/conversations with channel_type, sender_id, either participants[] or, for SMS campaigns, contacts (comma-separated numbers), groups (contact group ids) or message_contacts (reuse the recipients of an earlier message), and message (content, content_url, content_file, media_ids, metadata.template_id, metadata.template_variables, scheduled_for). An existing thread with the same contact is reused. A single recipient answers 201 with the conversation; a bulk send answers 201 with success_count, failed_count, total_count and, when the landline filter dropped numbers, warning_code, warning and warning_detail.
  5. Schedule and cancel: scheduled_for is Y-m-d H:i:s, must be in the future and is read in the user's timezone (or X-Timezone). The message sits with status 5 until delivery; DELETE /v2/conversations/{conversation}/messages/{message} cancels it and refunds the reserved credit.
  6. Organise: PATCH …/archive (no body), PATCH …/pin (is_pinned, omit to toggle), PATCH …/assign (user_id or department_id, null to unassign; account admin), PATCH …/read-status (status read or unread).
  7. Delivery: GET /v2/conversations/messages/{messageId} is one message or, with is-bulk=1, the bulk group it belongs to; POST /v2/conversations/messages/{message}/statuses lists the per-recipient statuses of a message or bulk group (is-bulk, filter[search] by number, filter[status], type, start, length), each with status, error_code, error_description and cost.
  8. Rules: GET /v2/conversations/settings and POST /v2/conversations/settings (account admin) hold, per channel key (sms, whatsapp), auto_assigning rules (numbers[] → assign_to {type: user|department, id}) and time_to_respond rules (numbers[] → minutes); available_numbers lists the numbers you can put in a rule. The whole settings object is replaced on every save.
  9. Be told, not poll: POST /v2/webhook-subscriptions with type message_received or message_sent sends every inbound or outbound message of any channel to your URL (payloads and delivery rules in the Webhooks guide).
  10. Prices: GET /v2/account/messaging-rates-countries then GET /v2/account/messaging-rates?country_code=IE: one row per channel (1 SMS, 2 WhatsApp with wa_message_type, 3 MMS) with the per-message price in the account currency.

Roles and access

  • Any authenticated user can list, open, start and reply; assign and the rules endpoints need an account admin (403 otherwise). Opening a thread the user may not see answers 403.
  • the WhatsApp for Business add-on enables channel 2 and the MMS option enables media_ids on channel 1; without them the input is ignored or answers code 6101.
  • The ISO dates option (per account) returns every timestamp as ISO 8601 in the requested X-Timezone; without it the thread and message timestamps are ISO 8601 in UTC with microseconds (2026-05-01T13:30:00.000000Z) and X-Timezone is ignored. See Dates and timezones.

Pitfalls

  • channel_type, message_type and every status are integers; direction is a string.
  • One contact, one thread: a number that writes to you on SMS and on WhatsApp shares a conversation, with both channels in channels. Send channel_type with the reply, or the thread's default channel is used.
  • A WhatsApp thread with expires_at in the past accepts templates only; see the WhatsApp guide. SMS threads have expires_at: null.
  • An inbound WhatsApp file that could not be fetched arrives as a message without content_url and with metadata.media_error.code (MEDIA_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, MEDIA_DOWNLOAD_FAILED, MEDIA_PROCESSING_FAILED, MEDIA_TOO_LARGE_PROVIDER).
  • The SMS group still serves the older inbox, timeline and sent-history endpoints the portal's SMS pages use; they return the same messages in DataTables-style shapes and are documented in the SMS guide. New integrations should read through this group.