SMS Logs

API endpoints related to managing SMS Logs. SMS logs contain records of text message conversations between customers and Agents. They are linked to an Organization.

Note: SMS log endpoints require an API key scoped to the organization in the path. Requests made with an API key that belongs to a different organization return 401 Unauthorized.

Get SMS Logs

Retrieves a paginated list of SMS logs for a given organization, most recent first.

GET /v1/organizations/{organizationId}/sms-logs

Path Parameters:

• organizationId (string, required): The unique identifier of the organization.

Query Parameters:

• limit (number, optional): Number of results per page (1-100). Defaults to 50.
• nextCursor (string, optional): Opaque cursor for fetching the next page of results. Pass the nextCursor value returned by the previous page. Omit it to fetch the first page.
• archivedOnly (boolean, optional): Return only archived SMS logs.
• includeArchived (boolean, optional): Include archived SMS logs alongside active ones.

Note: archivedOnly and includeArchived are mutually exclusive — you cannot use both at the same time.

Headers:

• x-api-key (string, required): Your API key for authentication.

Response:

• 200 OK: SMS logs retrieved successfully. limit caps the returned SMS logs, independently of the internal database read size. The endpoint skips filtered-empty internal pages within a bounded search budget. When hasMore is true, continue with nextCursor, even if data is empty. An empty page with a cursor means the search has more records to examine; only hasMore: false means the query is exhausted. Reaching the search budget returns a normal 200 continuation page, not a 503 error.

  {
    "message": "Successfully retrieved organization sms logs",
    "data": [
      {
        "id": "sms_123abc",
        "organizationId": "org_123abc",
        "agentId": "agent_123abc",
        "phoneNumber": "+15551234567",
        "contactName": "John Smith",
        "status": "active",
        "direction": "inbound",
        "summary": "Customer asked about upcoming appointment availability.",
        "isViewed": true,
        "messageCount": 4,
        "lastMessageAt": 1698408100000,
        "messages": [
          {
            "id": "msg_001",
            "role": "customer",
            "message": "Hi, do you have any openings this week?",
            "direction": "inbound",
            "timestamp": 1698407100000
          },
          {
            "id": "msg_002",
            "role": "agent",
            "message": "Hi John! Yes, we have availability on Thursday at 2 PM and Friday at 10 AM. Would either of those work for you?",
            "direction": "outbound",
            "timestamp": 1698407130000
          }
        ],
        "metadata": {
          "agentNumber": "+15559876543",
          "externalNumber": "+15551234567"
        },
        "createdAt": 1698407100000,
        "updatedAt": 1698408100000
      }
    ],
    "nextCursor": "eyJwayI6Ik9SR0FOSVpBVElPTl9TTVNfTE9HLi4uIn0=",
    "hasMore": true
  }

• 400 Bad Request: Invalid or expired API key, both archivedOnly and includeArchived were provided, or nextCursor is not a cursor this endpoint returned (Invalid cursor).
• 401 Unauthorized: The API key does not belong to the organization in the path.
• 404 Not Found: Organization not found.

Try it yourself

GET/v1/organizations/{organizationId}/sms-logs

ProductionDevelopment

Query Parameters (optional)

limit:

nextCursor:

archivedOnly:

includeArchived:

API Key

Request URL: https://api.askbenny.ca/v1/organizations/{organizationId}/sms-logs

Get SMS Log By ID

Retrieves details for a specific SMS log. Automatically marks the log as viewed if it hasn't been viewed yet.

GET /v1/organizations/{organizationId}/sms-logs/{smsLogId}

Path Parameters:

• organizationId (string, required): The unique identifier of the organization.
• smsLogId (string, required): The unique identifier of the SMS log.

Headers:

• x-api-key (string, required): Your API key for authentication.

Response:

• 200 OK: SMS log details retrieved successfully.

  {
    "message": "Successfully retrieved organization sms log by id",
    "data": {
      "id": "sms_123abc",
      "organizationId": "org_123abc",
      "agentId": "agent_123abc",
      "phoneNumber": "+15551234567",
      "contactName": "John Smith",
      "status": "completed",
      "direction": "inbound",
      "summary": "Customer booked a Thursday 2 PM appointment.",
      "isViewed": true,
      "messageCount": 6,
      "lastMessageAt": 1698408500000,
      "messages": [
        {
          "id": "msg_001",
          "role": "customer",
          "message": "Hi, do you have any openings this week?",
          "direction": "inbound",
          "timestamp": 1698407100000
        },
        {
          "id": "msg_002",
          "role": "agent",
          "message": "Hi John! Yes, we have availability on Thursday at 2 PM and Friday at 10 AM. Would either of those work for you?",
          "direction": "outbound",
          "timestamp": 1698407130000
        },
        {
          "id": "msg_003",
          "role": "customer",
          "message": "Thursday at 2 PM works great!",
          "direction": "inbound",
          "timestamp": 1698407200000
        },
        {
          "id": "msg_004",
          "role": "agent",
          "message": "You're all set for Thursday at 2 PM. We'll send you a reminder the day before. See you then!",
          "direction": "outbound",
          "timestamp": 1698407230000
        }
      ],
      "metadata": {
        "agentNumber": "+15559876543",
        "externalNumber": "+15551234567"
      },
      "createdAt": 1698407100000,
      "updatedAt": 1698408500000
    }
  }

• 400 Bad Request: Invalid or expired API key.
• 401 Unauthorized: The API key does not belong to the organization in the path.
• 404 Not Found: SMS log or organization not found.

Try it yourself

GET/v1/organizations/{organizationId}/sms-logs/{smsLogId}

ProductionDevelopment

API Key

Request URL: https://api.askbenny.ca/v1/organizations/{organizationId}/sms-logs/{smsLogId}

Update SMS Log

Updates details for an existing SMS log.

PATCH /v1/organizations/{organizationId}/sms-logs/{smsLogId}

Path Parameters:

• organizationId (string, required): The unique identifier of the organization.
• smsLogId (string, required): The unique identifier of the SMS log to update.

Headers:

• Content-Type (string, required): Must be set to application/json.
• x-api-key (string, required): Your API key for authentication.

Request Body:

{
  "status": "completed",
  "contactName": "Jonathan Smith",
  "summary": "Customer booked appointment for Thursday.",
  "isViewed": true
}

Updatable Fields:

• status (string, optional): Conversation status. Options: active, completed, failed.
• direction (string, optional): Conversation direction. Options: inbound, outbound, both.
• contactName (string, optional): Updated contact name.
• summary (string, optional): Conversation summary.
• isViewed (boolean, optional): Whether the log has been viewed.
• archivedAt (number | null, optional): Timestamp for archiving, or null to unarchive.

Fields outside this list are ignored.

Response:

• 200 OK: SMS log updated successfully.

  {
    "message": "Successfully updated organization sms log",
    "data": {
      "id": "sms_123abc",
      "organizationId": "org_123abc",
      "agentId": "agent_123abc",
      "phoneNumber": "+15551234567",
      "contactName": "Jonathan Smith",
      "status": "completed",
      "direction": "inbound",
      "summary": "Customer booked appointment for Thursday.",
      "isViewed": true,
      "createdAt": 1698407100000,
      "updatedAt": 1698412700000
    }
  }

• 400 Bad Request: Invalid input data or invalid API key.
• 401 Unauthorized: The API key does not belong to the organization in the path.
• 404 Not Found: SMS log or organization not found.

Try it yourself

PATCH/v1/organizations/{organizationId}/sms-logs/{smsLogId}

ProductionDevelopment

API Key

Request Body

{ "status": "completed", "contactName": "Jonathan Smith", "summary": "Customer booked appointment for Thursday.", "isViewed": true }

Request URL: https://api.askbenny.ca/v1/organizations/{organizationId}/sms-logs/{smsLogId}

Delete SMS Log

Deletes or archives a specific SMS log.

DELETE /v1/organizations/{organizationId}/sms-logs/{smsLogId}

Path Parameters:

• organizationId (string, required): The unique identifier of the organization.
• smsLogId (string, required): The unique identifier of the SMS log to delete.

Query Parameters:

• archive (boolean, optional): Set to true to archive instead of permanently deleting.

Headers:

• x-api-key (string, required): Your API key for authentication.

Response:

• 200 OK: SMS log deleted or archived successfully.

  {
    "message": "Successfully archived organization sms log"
  }

• 400 Bad Request: Invalid or expired API key.
• 401 Unauthorized: The API key does not belong to the organization in the path.
• 404 Not Found: SMS log or organization not found.

Try it yourself

DELETE/v1/organizations/{organizationId}/sms-logs/{smsLogId}

ProductionDevelopment

Query Parameters (optional)

archive:

API Key

Request URL: https://api.askbenny.ca/v1/organizations/{organizationId}/sms-logs/{smsLogId}

SMS Log Statuses

Status	Description
active	Conversation is ongoing
completed	Conversation has ended naturally
failed	Message delivery or agent processing failed

Message Directions

Direction	Description
inbound	Customer initiated the conversation
outbound	Agent or campaign initiated the conversation
both	Conversation includes both inbound and outbound messages