SMS/MMS Messaging (V2)

SMS/MMS Messaging (V2)

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:
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)