NUACOM API

Messaging

Conversations / SMS

SMS is the first channel of Conversations: credit bought in packages, an approved sender name, optional templates, and three ways to send. This guide follows the portal's New Message page and its Sent History and SMS Inbox reports, and covers MMS, which is an SMS with media_ids for US, Canadian and Australian numbers. Forwarding inbound SMS to email is configured in the portal (Settings → SMS).

Before you send

  1. Credit: GET /v2/sms/packages lists the packages (id, amount of credits, cost); POST /v2/top-up/sms/calculate with package_id quotes amount, vat and total; POST /v2/top-up/sms with package_id and a saved payment_method buys it (account admin; 400 with error_code PAYMENT-INCOMPLETE means the card needs 3-D Secure in the portal). Auto top-up is GET, POST (package_id, payment_method, credit_limit) and DELETE /v2/top-up/auto/sms. The balance is sms_balance on the account info.
  2. Sender name: GET /v2/sms/sender_names returns the approved names (filter[channel]=sms; whatsapp returns the WhatsApp numbers instead, each row carries channel). POST /v2/sms-sender-name (account admin) requests a new one: sender_name of 3 to 11 letters and digits, not digits only; is_ireland_sender: true when it will write to Irish numbers, which registers it with ComReg (the organisation and contact fields on the request are the ComReg details). Approval is manual; until then the name is absent from the list and an Irish send answers code 6004.
  3. Templates (optional): GET /v2/sms-templates with filter[channel]=1, filter[status]=1, filter[search], filter[usage] (sms, 10dlc, whatsapp), sort, page, per_page; POST /v2/sms-templates with name, message_text, channel: 1, sender_id, opt_in, opt_out; PUT and DELETE /v2/sms-templates/{smsTemplate}. Status codes are the same as for WhatsApp (1 approved is the one you can send with).
  4. US numbers (10DLC): a message to a +1 number must reference an approved campaign template, otherwise the send answers code 6005 (6106 for an unverified toll-free number). The campaign is requested with the same POST /v2/sms-templates, adding config (description, message_samples[], use_cases[] from additional=campaign_use_cases, will_include_links, will_include_phone_numbers, opt_in_description); the resulting template has usage: "10dlc", cannot be edited, and lists the campaign's numbers in sender_names. Send it with template_id, and leave from empty to let NUACOM pick a campaign number.

Sending (what the portal does)

  • The compose flow (New Message page): GET /v2/sms/search-contacts?q= suggests up to five phonebook entries (name, number); POST /v2/sms/overview stages the message and quotes it: from, message, recipients as contacts (comma-separated numbers), groups (contact group ids) or message_contacts (the reference of an earlier send), template_id, time_to for a scheduled send, send_to_opted_in, opt_in / opt_in_message, opt_out / opt_out_message, the landline filter (ll_sniff, ll_sniff_from, ll_sniff_to, ll_last_activity, ll_visits_times, ll_visits_operation), channel_type (1 SMS, 2 WhatsApp), media_ids for MMS and an sms_session of your own (any string up to 32 characters; reuse it to overwrite the staged draft). The answer carries sms_session_id, the valid, invalid and opted-out numbers, the segment count and the credit it will use. The portal's Send button then sends the staged draft; through the API, send with POST /v2/sms/send once the quote looks right.
  • One call: POST /v2/sms/send with from, message, to[] (number, optional reference echoed back), optional send_at (Y-m-d H:i:s; within two minutes it is sent at once), template_id and media_ids. The answer is status (sent, scheduled, partial, failed), success_count, failed_count and numbers[] with number, international_number, reference, valid, message_id, status and error. Keep message_id: it is the key for the status endpoints.
  • In a thread: POST /v2/conversations and POST /v2/conversations/{conversation}/messages with channel_type: 1, described in the Conversations guide. This is the path for a reply inside an existing thread.
  • Appointment reminders: POST /v2/sms/appointment with contacts, sender_name, date_to_send, time_zone, send_before (for example 1day) and sms_session schedules the reminder relative to the appointment and answers recipient, sms_message, scheduled_for and new_session_id.
  • MMS: on accounts with the MMS option and every recipient in the US, Canada or Australia, upload each file first with POST /v2/mms/media (multipart file; up to 10 files per message, images up to 5 MB, other files up to 500 KB) and pass the returned ids as media_ids. Images and videos are moderated asynchronously: poll GET /v2/mms/media/{mediaId}/moderation-status until approved, or the send answers 6105. MMS has its own rate in the messaging rates.

Result codes: a failed send answers 400, 402 or 422 with a code in the body. 6001 insufficient credit, 6002 no valid recipient, 6003 invalid sender, 6004 the sender is not approved for Irish numbers, 6005 US campaign not approved, 6006 delivery failed, 6007 scheduling error, 6008 partial bulk failure, 6009 whole bulk failed, 6010 draft not found, 6011 message limit reached, 6012 too many requests, 6013 auto top-up failed, 6014 send failed after the top-up; 6101 MMS disabled, 6102 MMS country not supported, 6103 too many files, 6104 media not found, 6105 media not approved yet, 6106 toll-free number not verified.

Reading

  • New integrations read through GET /v2/conversations and the message status endpoints of the Conversations guide.
  • Sent History: POST /v2/sms/history is the report behind the portal's Sent History page, in DataTables form: iDisplayStart, iDisplayLength, sSearch, type (message type filter), search_by_number and sEcho in; sEcho, iTotalRecords, iTotalDisplayRecords and aaData[] out, one row per message or per bulk send (bulk_id, status.counts) with message_id, conversation_id, channel_type, sender_id, destination_e164, message_text, scheduled_for, sent_by and the actions the portal may offer. A bulk row expands with GET /v2/conversations/messages/{messageId}?is-bulk=1 and POST /v2/conversations/messages/{message}/statuses?is-bulk=1.
  • Inbox: GET /v2/sms/inbox lists inbound SMS and WhatsApp messages, newest first (iDisplayStart, iDisplayLength, filter), as _embedded[] with date, sender, number, number_name_sender, number_name_dst, message, channel_type, message_type, content_url, content_filename, media_error, plus total_items.
  • Thread by numbers: GET /v2/sms/timeline?src_number=&dst_number= returns every SMS and WhatsApp message exchanged between two numbers, same row shape.
  • Combined feed: GET /v2/sms is a paginated union of inbound and outbound SMS (page, pageSize, filter), kept for older clients.

Roles and access

  • Any authenticated user can send and read; buying credit, requesting a sender name and managing 10DLC campaigns need an account admin.
  • The MMS option, enabled per account by NUACOM, allows media_ids; without it the field is ignored on the overview and answers 6101 on a direct send.
  • The ISO dates option switches scheduled_for and the history dates to ISO 8601 in the requested X-Timezone.

Pitfalls

  • Numbers may be sent as +353…, 00353… or local Irish format; the answer echoes international_number. The inbox and timeline hold international digits without +.
  • send_at and time_to are read in the user's timezone, not UTC; a value within two minutes is sent immediately.
  • The compose flow is two calls: overview only stages. A staged draft that is never sent stays as a hidden conversation.
  • POST /v2/sms/history is a POST although it only reads; the GET of the same path is a deprecated legacy report and is not part of the reference.
  • opt_in / opt_out append their text to the message and count toward its segments; opted-out numbers are dropped silently from the counts, not reported as errors.