Fetching SMS/MMS Conversation List:

REQUEST: GET https://pbx.primevox.net/api/messaging/v1/conversations

• URL PARAMS: All parameters are Case Sensitive.
• auth is the string of text in the phone system's Advanced menu. It looks like a lot of nonsense.
• containerID is the 6-digit Container ID number that is present in the top-left corner of the Dashboard when logged into a particular container.
• phoneNumber is the phone number belonging to a PrimeVOX customer on this Container

RESULT: Application/json - Either a Conversations blob or an Error blob:

• "conversations": (Code 200)
  • {conversationId}: (used for fetching individual messages)
    • "conversationWith" (Phone number of remote party)
    • "hasUnreadMessages" (1 if there are unread messages in conversation)
    • "lastMessageDate" (Date of the most recent message in conversation)
• "error":
  • "API Key and Container ID are both required." (Code 401)
  • "Either you left out the phoneNumber parameter, or you are trying to text with a non-USA number." (Code 400)
  • "The supplied API Key is invalid." (Code 401)
  • "The phone number you provided does not exist in this container." (Code 404)
  • "Error connecting to the database, please try again later."  (Code 500)

Fetching SMS/MMS Messages in Conversation:

REQUEST: GET https://pbx.primevox.net/api/messaging/v1/conversation

• URL PARAMS: All parameters are Case Sensitive.
• auth is the string of text in the phone system's Advanced menu. It looks like a lot of nonsense.
• containerID is the 6-digit Container ID number that is present in the top-left corner of the Dashboard when logged into a particular container.
• conversationID is the unique identifier of an existing SMS conversation

RESULT: Application/json - Either a Messages blob or an Error blob:

• "messages": (Code 200)
  • {messageId}: (used for fetching individual messages)
    • "messageDate" (Date of this message, in UTC)
    • "messageFrom" (Number of the party who sent this message)
    • "messageText" (Text of the message, full Unicode support for emojis)
      • Important: See note below about MMS attachments
• "error":
  • "API Key and Container ID are both required." (Code 401)
  • "You must include a ConversationID to fetch." (Code 400)
  • "The supplied API Key is invalid." (Code 401)
  • "Error connecting to the database, please try again later."  (Code 500)

Fetching MMS Attachments

When an MMS (multimedia message) comes in, messageText will contain the following string:

• media:MEDIA_ID|mime:MIME_TYPE

You can use the MIME_TYPE above to identify if the media is previewable (like an image you want to embed in a conversation, or it may be a binary file that can't be embedded).

To generate a URL used to download/preview the media attachment, use the following syntax:

• https://pbx.primevox.net/ucp_sms_convo_download_attachment.php?bypassContainer={CONTAINER_ID}&media={MEDIA_ID}

Replace the {CONTAINER_ID} with the containerID of the customer you're working with, and replace {MEDIA_ID} with the media ID fetched in the message. Obviously, do not include curly braces. Just text.

The above URL will send the proper headers and MIME types for browsers to download and/or display the file. Please use lazy loading to avoid hammering our file server too much.

Send an SMS/MMS:

REQUEST: POST https://pbx.primevox.net/api/messaging/v1/sendMessage.php

• JSON BODY: All parameters are Case Sensitive, and must be in the JSON body.
• auth is the string of text in the phone system's Advanced menu. It looks like a lot of nonsense.
• containerID is the 6-digit Container ID number that is present in the top-left corner of the Dashboard when logged into a particular container.
• fromNumber is the PrimeVOX customer's phone number
• toNumber is the phone number of the message's destination
• messageText is the text of the message, full unicode (emojis) supported

RESULT: Application/json - Either a Success blob (with the conversationID) or an Error blob:

• "success": (Code 200)
  • "messageId" (Unique identifier of your sent message)
  • "conversationId" (Unique identifier of the conversation this message can be fetched)
• "error":
  • "API Key and Container ID are both required." (Code 401)
  • "You must include a USA fromNumber and USA toNumber." (Code 400)
  • "Carrier rejection, your messageText cannot be longer than 1600 characters." (Code 400)
  • "You do not have permission to send from that Phone Number." (Code 401)
  • "The supplied API Key is invalid." (Code 401)
  • "Error connecting to the database, please try again later."  (Code 500)