NUACOM API

Numbers & call routing

Softphone Announcements

Softphone announcements are audio clips an agent can play into a live call from the NUACOM softphone. Each one has a name, a description, one audio file (MP3, WAV or OGG) and a duration. This group holds the list, one announcement, create, update (JSON on PUT, multipart on POST), delete and the audio download. They are not the announcements IVRs and queues play: those are announcement slots uploaded with POST /v2/announcements/upload-audio and described in IVR.

Workflow (what the portal does)

  1. List: GET /v2/softphone-announcements answers every announcement of the account as an array of {id, account_id, name, description, filename, size, duration}; no paging and no filters. size is in bytes; filename is the storage name the API generated, not the name you uploaded.
  2. Create: POST /v2/softphone-announcements as multipart/form-data with name (1–25 characters), description (up to 150 characters, optional), the audio as file (MP3, WAV or OGG) or as base64_file (a data URI, see below), and duration, the clip length in seconds, required whenever audio is sent. Answers 201 with the announcement. An account holds at most 100 announcements.
  3. Edit the text: PUT /v2/softphone-announcements/{id} with a JSON body carrying any of name, description and duration; keys you leave out keep their value. Answers 204, or 404 when the id is not one of the account's.
  4. Replace the audio: a file travels as multipart/form-data, which PHP does not read on PUT, so the portal sends it with POST /v2/softphone-announcements/{id}: file plus duration, and optionally name and description. It is the same operation as the PUT, which can replace the audio too, through base64_file in the JSON body. The previous file is deleted. Answers 204.
  5. Play or download: GET /v2/softphone-announcements/{id}/audio answers the audio bytes with Content-Type, Content-Length and Content-Disposition: attachment; filename="…"; 404 when the announcement, or its file, does not exist. GET /v2/softphone-announcements/{id} answers the record alone.
  6. Delete: DELETE /v2/softphone-announcements/{id} removes the record and its file. 204, or 404.

After a create or an update the account's connected softphones are notified of the change; the notification is best-effort and never fails the request.

# Create from an MP3 file
curl -X POST https://api.api-nuacom.com/v2/softphone-announcements \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'name=Call recording notice' \
  -F 'description=Played before taking card details' \
  -F 'file=@recording-notice.mp3' \
  -F 'duration=12'
# → 201 {"id": 41, "account_id": "IE-00123", "name": "Call recording notice", "description": "Played before taking card details", "filename": "IE-00123-6901a1b2c3d4e.mp3", "size": 196608, "duration": 12}

# Rename it
curl -X PUT https://api.api-nuacom.com/v2/softphone-announcements/41 \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"name": "Recording notice"}'
# → 204

# Replace the audio: POST, not PUT
curl -X POST https://api.api-nuacom.com/v2/softphone-announcements/41 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@recording-notice-v2.wav' -F 'duration=14'
# → 204

# Download it
curl -o notice.wav https://api.api-nuacom.com/v2/softphone-announcements/41/audio \
  -H 'Authorization: Bearer YOUR_API_KEY'

Audio formats and limits

Input Accepted Notes
file (multipart) MP3, WAV, OGG Checked on the content, not on the file name; the stored name gets the extension the content implies
base64_file data:audio/wav;base64,…, data:audio/mpeg;base64,…, data:audio/ogg;base64,… The declared type must match the content (audio/x-wav and the other x- spellings count as the same type); anything that looks like a URL or a file path is rejected; the stored file is always named .wav
  • name: 1–25 characters. description: up to 150 characters; stored as "" when left out on create.
  • duration: a number, required whenever file or base64_file is sent; the API stores and returns it as a whole number and does not check it against the audio.
  • No maximum file size is validated by the API.
  • At most 100 announcements per account.

Roles and access

  • Every endpoint in this group is open to any authenticated user of the account; none requires an account admin.

Pitfalls

  • GET /v2/softphone-announcements/{id} answers 200 with {} for an id that is not one of the account's; the update, delete and audio endpoints answer 404.
  • The 101st announcement is refused with 500, not 422.
  • A multipart body on PUT is ignored: the request answers 204 and changes nothing. Send files with POST /v2/softphone-announcements/{id}.
  • duration is required with file and base64_file (422 otherwise), on an update as well as on create.
  • When both file and base64_file are sent, file is used.
  • A base64 upload is stored as .wav whatever audio type the data URI declares; prefer multipart for MP3 and OGG.
  • Deleting does not notify the softphones; creating and updating do.
  • The download is served as an attachment under the stored file name, not the one you uploaded.