NUACOM API

Calls

Reports / Missed Call Follow-up

The Missed Call Follow-up report, GET /v2/missed-call-report in Reports, lists the callers who were not answered and have not been called back. This sub-group schedules an email summary of it: one setting per account and report page, holding the recipients, the period the email covers, the hour it is sent at and the timezone of both. Four endpoints: read the setting, create or update it, delete it, and send the email now.

Workflow (what the portal does)

The portal's Get Email Updates button on the report, shown to account admins only, drives all four:

  1. Read: GET /v2/missed-call-followup-settings/{reportId} with the report id (34, see Report ids) pre-fills the form. It answers 200 with {"data": {"id", "account_id", "report_id", "email", "period", "hour", "timezone", "is_enabled"}}, or 200 with {"data": null, "message": "No settings found for this report."} when nothing is configured yet, not 404. timezone is the effective one: the value saved, or the account's timezone when none was.

  2. Save: POST /v2/missed-call-followup-settings creates the setting or replaces the existing one for that report_id. The portal sends email, report_id and timezone and leaves the rest to the defaults.

    Field Required Rules
    email yes One or more addresses separated by commas, 2000 characters at most; every address must be valid
    report_id yes 34 or 340
    period no daily (default), weekly or monthly
    hour no The hour to send at, as HH:00; 08:00 by default
    timezone no An IANA name such as Europe/Dublin; the account's timezone by default
    is_enabled no true by default; false keeps the setting but stops the emails

    It answers 200, on create as well, with {"message": "Settings saved successfully.", "data": {…}}, the same data as the read. Validation failures answer 422 with errors, for instance Invalid report ID. Must be 34 or 340., Invalid hour format. Must be in HH:00 format (e.g., 08:00). or Invalid email address(es): ….

  3. Delete: DELETE /v2/missed-call-followup-settings/{reportId} answers 200 with {"message": "Settings deleted successfully."}, or 404 with {"message": "No settings found to delete."}.

  4. Send now: POST /v2/missed-call-followup-settings/{reportId}/send-now queues the email immediately, with the saved period and recipients, and answers 200 with {"message": "Report has been queued and will be sent shortly."}, or 404 when no setting exists for that id. NUACOM enables it per account; elsewhere it answers 403 with {"message": "This endpoint is not available for your account."} and the portal hides the button.

curl -X POST https://api.api-nuacom.com/v2/missed-call-followup-settings \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email": "reception@example.com,manager@example.com", "report_id": 34, "period": "daily", "hour": "08:00", "timezone": "Europe/Dublin"}'
# → {"message": "Settings saved successfully.", "data": {"id": 17, "account_id": "IE-00123", "report_id": 34, "email": "reception@example.com,manager@example.com", "period": "daily", "hour": "08:00", "timezone": "Europe/Dublin", "is_enabled": true}}

The scheduled email

  • When: NUACOM's scheduler runs once an hour and sends a setting when the current hour in its timezone equals hour, so the email arrives within that hour. daily sends every day, weekly on Sundays, monthly on the first day of the month.
  • Which period: daily covers yesterday, 00:00:00 to 23:59:59 in the setting's timezone; weekly the seven days before today; monthly from the same day of the previous month to yesterday, which is the previous calendar month when sent on the 1st.
  • What it says: the subject is NUACOM - Missed Call Follow-up Report (your own brand name on a branded account). The body is titled Yesterday's, Last Week's or Last Month's Missed Calls Report and reads "On <first day of the period> you had: Missed N call(s), Returned N call(s), Remaining N call(s)", with a link to the report page in the portal. When all three are zero it says you had zero missed calls instead.
  • How it counts: Missed is the number of callers from outside the account whose inbound call was not answered in the period, calls that ended in voicemail or an announcement included, one per number, leaving out those who were called back or who called again and got through before the period ended, and leaving out withheld numbers and system short codes: the rows the account-wide report shows for that period. Returned is how many of those numbers have since received an answered outbound call from the account, up to the moment the email is generated. Remaining is the difference.
  • Who receives it: every address in email, in one message; recipients need not be portal users.
  • What it does not do: it covers the whole account, with no queue or extension filter, and it does not list the calls. The queue each call was waiting in is in the report rows (call_in_queue, call_in_queue_name) and in the CSV export, see Reports.
  • When it stays silent: a disabled setting, an account that is not active, or an email without a single valid address: nothing is sent and nothing is reported back.

How the scheduled summary is sent

flowchart TD
    save["POST /v2/missed-call-followup-settings<br/>email, period, hour, timezone"] --> wait["Scheduler runs once an hour"]
    wait --> hourMatch{"Current hour in setting's timezone == hour?"}
    hourMatch -- "no" --> wait
    hourMatch -- "yes" --> gate{"is_enabled, account active,<br/>email has a valid address?"}
    sendNow["POST .../{reportId}/send-now"] --> gate
    gate -- "no" --> silent["Nothing sent, nothing reported back"]
    gate -- "yes" --> compute["Compute Missed / Returned / Remaining for the period"]
    compute --> email["Email every address in email, one message"]

Report ids

report_id names the portal report page the setting belongs to and the email links to: 34 is the Missed Call Follow-Up report, the view of GET /v2/missed-call-report; 340 is its account-wide version, GET /v2/admin-missed-call-report. The two ids hold independent settings, but the email is the same for both: account-wide counts, as above. The portal reads and saves 34 from both pages, so a setting saved under 340 is never shown there.

Roles and access

  • All four endpoints require an account admin; any other user gets 403 with the body "Forbidden". An API key acts as the admin who created it.
  • The setting belongs to the account, not to the user who saved it: every admin reads and changes the same one.
  • Send now is additionally restricted to the accounts NUACOM has enabled it for (403 with a message otherwise).

Pitfalls

  • hour must be zero-padded: 8:00 passes validation but never matches the scheduler's hour, so the email is never sent. Send 08:00.
  • Saving replaces the whole setting. An omitted period, hour, timezone or is_enabled goes back to its default; send every field each time, not only the one you change.
  • The read answers 200 with data: null when nothing is configured; only the delete answers 404.
  • Send now answers 200 "queued" even when the setting is disabled, the account is not active or no recipient is valid; in those cases nothing is sent.
  • Only 34 and 340 are accepted on save; the read, delete and send-now endpoints accept any integer and simply find nothing.
  • timezone must be an IANA name; abbreviations and offsets are rejected with Invalid timezone.
  • The date in the email is the first day of the period: on a weekly or monthly report it is not the day the email was sent.