Home

For Developers

Help Docs Developer Resources Messaging API Messaging API

Messaging API Documentation

Use these endpoints to manage a “send yourself” messaging project.

Sending modes

There are 2 modes in sending texts yourself: Concurrent and Fast.

Concurrent mode requires 2 API calls to send a message and all contacts must be imported beforehand:

  1. Ask the system via /api/message/next for the next contact in a project, this call makes sure only one contact is returned at any time to avoid duplicate texts and allowing many texters to send the same project at the same time.
  2. Use the data from the previous call to actually send the message using /api/message/send. This call schedules the text for delivery or returns an error if delivery is not possible.

Fast mode requires only one API call and no contacts required to be imported. This mode assumes you have the list of contacts and ability to go over that list. This mode can be used if authorized only, submit a ticket to our support to enable it for your account.

In fast mode you pull a contact phone from your list and send it by using /api/message/send.

New contacts will be created in our system automatically, for already existing contacts all tags will be honored as usual, i.e. dnd tags will be skipped… All responses will be tagged in our system, to sync with your database use our Webhooks.

Message Log Object

This object is used in webhooks and this API and represents a single messaging event for both incoming and outgoing texts.

  • cid - account ID
  • logid - unique message ID
  • flags - tags applied to this message including supplied tags
  • sender - sender of the message, user id or number, when it is equal to the phone field this means incoming text, same as status=received
  • proxy - a proxy number that sent or received message
  • phone - a contact phone number, it is unique within the account (cid)
  • tcr_cid - TCR campaign id
  • sent_time - timestamp when the message was sent
  • update_time - last status update timestamp
  • text - text of the message sent/received
  • file - attachment URL for MMS messages
  • group - a group this contact belongs to at the time the message was sent
  • action - action this message was part of
  • status - delivery status: received, delivered, undelivered, failed
  • status_code - original error code we received in webhook, may not be the same as errcode, this code may be present even for delivered messages
  • error_text - undelivered error explanation
  • error_code - normalized error code
  • error_subcode - additional code for cases of complex errors
  • price - what we charged for this message
  • tracking - our short URL used in this message, ID and domain for tracking purposes
  • contact_flags - a list of all contact flags currently assigned, webhooks only
  • contact_source - the contact source field, webhooks only

Get Next Contact

  • Endpoint: /api/message/next
  • Method: GET or POST
  • Description: Retrieves the next available contact for messaging in concurrent mode. This request “locks” the contact for a short period of time, i.e. this contact will not be visible and available to anyone for the 5 minutes.
  • Request Parameters:
    • action (String, required): Specifies the messaging action ID
  • Response:
    • Success: Returns contact details in JSON format.
    • Error: Returns an error message.
  • Special error cases:
    • 404 - error status 404 means there are no more contacts available, i.e. you reached the end of the list
    • 441 - this is a temporary error condition, due to high concurrency and competition this request returns no contact but there are still more contacts available, just retry in a couple of seconds
Example Usage
POST /api/message/next
{
  "action": "125"
}
Example Response
{
  "cid": "c_example123",
  "phone": "9876543210",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "1234567890"
}

Send a Message

  • Endpoint: /api/message/send

  • Method: POST

  • Description: Sends a message to a specified contact previously retrieved with /api/message/next request.

  • Request Body Parameters:

    • phone (String, required): Contact phone number (must be valid)
    • action (String, required): Specifies the messaging action ID
    • text (String, required): Message text
    • flags (List, optional): Additional tags to be applied to the message record, not contact.
    • fast mode only parameters:
      • name (String, optional) - name for new contact, if not provided new contacts will have the phone number as first name
      • group (Number, optional) - optional group id where to put new contacts, the group must exist

  • Response:

    • Success: Returns a log of the message sent.
    • Error: Returns an appropriate error message when validation fails.
Example Usage
POST /api/message/send
{
  "phone": "1234567890",
  "action": "125",
  "text": "Hello STOP to opt out"
}
Example Response
{
    "cid": "c_example123",
    "logid": "rl_693c81daa5bf42d58a390e791d584ed1",
    "action": "125",
    "text": "Hello STOP to opt out",
    "sender": "u.....",
    "sent_time": "04/17/2025 12:15pm EST",
    "phone": "5555151505",
    "group": "26",
    "flags": [ "sent", "newsms" ],
    "file": "http://host.com/action/c_example123/125.png",
    "proxy": "2028456736",
    "price": -0.14
}

Get Message Logs

  • Endpoint: /api/message/log/select
  • Method: GET or POST
  • Description: Retrieve a contact conversation log, i.e. all messages sent and received for a contact.
  • Rquest Body Parameters:
    • phone - List of contact numbers separated by comma.
    • proxy - List of proxy numbers separated by comma.
    • logid - List of message ids separated by comma.
    • flags - List of message flags/tags.
    • tcr_cid - List of TCR campaign ids separated by comma.
    • since - message start date in milliseconds or human date/time format
    • before - message end date in milliseconds or human date/time format
    • _start - Next token returned in the previous request for pagination.

Example Request:

curl -u CID:KEY 'https://app.rumbleup.com/api/message/log/select?phone=5551112233'

Example Response:

{
    "count": 3,
    "total": 3,
    "next_token": "....",
    "data": [
       {
        "logid": "rl_693c81daa5bf42d58a390e791d584ed1",
        "flags": [],
        "sender": "u_......",
        "proxy": "5552023344",
        "phone": "5551012233",
        "tcr_cid": "C1245C",
        "sent_time": "04/17/2025 12:15pm EST",
        "update_time": "04/17/2025 12:15pm EST",
        "text": "testing messages STOP to opt out",
        "price": -0.09
       }
    ]
}