In order to configure/control PRODUCT, please use URL: http://ip-of-server-where-PRODUCT-is-installed/api.php

Contents

Learn about OTA campaigns – YateOTA Requests, YateOTA Responses and YateOTA Errors

Request: query_campaigns

Retrieve aggregated information about OTA campaigns.

Requests

Responses

Errors

Requests

This request has multiple formats in which it can be sent:

{
    "request": "query_campaigns",
    "node": "ota",
    "params": {}
}
{
    "request": "query_campaigns",
    "node": "ota",
    "params": {
        "limit": "Number of campaigns to return",
        "offset": "The starting point to return campaigns"
    }
}
{
    "request": "query_campaigns",
    "node": "ota",
    "params": {
        "campaign_id": "Return a single campaign by specifying the campaign_id"
    }
}

Responses

Response has multiple formats depending on the sent request:

{
    "code": 0,
    "campaigns": [
        {
            "campaign": "Name of the campaign",
            "type": "Campaign Type",
            "participants": "Number of participants defined in campaign.",
            "finished": "Flag that shows if campaigned was finished or not. Bool format.",
            "pending_build": "Flag that shows if SMS construction has started. Bool format.",
            "pending_send": "Flag that shows if the SMS has started to be sent to the participants. Bool format.",
            "failed": "Flag that show if campaigned failed or not. Bool format.",
            "canceled": "Flag that show if campaigned is canceled or not. Bool format."
        }
    ]
}
{
    "code": 0,
    "campaigns": [
        {
            "campaign": "Name of the campaign",
            "type": "Campaign Type",
            "participants": "Number of participants defined in campaign.",
            "finished": "Flag that shows if campaigned was finished or not. Bool format.",
            "pending_build": "Flag that shows if SMS construction has started. Bool format.",
            "pending_send": "Flag that shows if the SMS has started to be sent to the participants. Bool format.",
            "failed": "Flag that show if campaigned failed or not. Bool format.",
            "canceled": "Flag that show if campaigned is canceled or not. Bool format."
        }
    ]
}
{
    "code": 0,
    "campaign": [
        {
            "campaign": "Name of the campaign",
            "type": "Campaign Type",
            "participants": "Number of participants defined in campaign.",
            "finished": "Flag that shows if campaigned was finished or not. Bool format.",
            "pending_build": "Flag that shows if SMS construction has started. Bool format.",
            "pending_send": "Flag that shows if the SMS has started to be sent to the participants. Bool format.",
            "failed": "Flag that show if campaigned failed or not. Bool format.",
            "canceled": "Flag that show if campaigned is canceled or not. Bool format."
        }
    ]
}

Errors

{
    "code": 404,
    "message": "Entity not found."
}

Examples: query_campaigns

Retrieve status for each campaign.

Request

Response

Request

{
    "request": "query_campaigns",
    "node": "ota",
    "params": {}
}

Response

{
    "code": 0,
    "campaigns": [
        {
            "campaign": "sched test rfm",
            "type": "rfm",
            "participants": 1,
            "finished": 1,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 0,
            "canceled": 0
        },
        {
            "campaign": "Interval Test",
            "type": "ram",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 0,
            "canceled": 1
        },
        {
            "campaign": "Test RAM",
            "type": "ram",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 1,
            "canceled": 0
        },
        {
            "campaign": "Test RAM 2",
            "type": "ram",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 1,
            "canceled": 0
        }
    ]
}

Retrieve status for a limited number of campaigns using parameters limit and offset.

Request

Response

Request

{
    "request": "query_campaigns",
    "node": "ota",
    "params": {
        "limit": 3,
        "offset": 0
    }
}

Response

{
    "code": 0,
    "campaigns": [
        {
            "campaign": "sched test rfm",
            "type": "rfm",
            "participants": 1,
            "finished": 1,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 0,
            "canceled": 0
        },
        {
            "campaign": "Interval Test",
            "type": "ram",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 0,
            "canceled": 1
        },
        {
            "campaign": "Test RAM",
            "type": "ram",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 1,
            "canceled": 0
        }
    ]
}

Retrieve status for a single campaign by specifying campaign_id.

Request

Response

Request

{
    "request": "query_campaigns",
    "node": "ota",
    "params": {
        "campaign_id": 147
    }
}

Response

{
    "code": 0,
    "campaigns": [
        {
            "campaign": "TEST RFM 03",
            "type": "rfm",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 1,
            "failed": 0,
            "canceled": 0
        }
    ]
}

Request: action_campaign

Modify a RAM/RFM OTA campaign status

Requests

Responses

Errors

Requests

{
    "request": "action_campaign",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign. Required.",
        "action": "stop/pause/restart"
    }
}

Responses

{
    "code": 0
}

Errors

{
    "code": 402,
    "message": "Missing all parameters."
}
{
    "code": 402,
    "message": "Missing required 'campaign_id' field."
}
{
    "code": 402,
    "message": "Missing required 'action' field."
}

Examples: action_campaign

Stop a running campaign.

Request

Response

Request

{
    "request": "action_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 144,
        "action": "stop"
    }
}

Response

{
    "code": 0
}

Pause a running campaign.

Request

Response

Request

{
    "request": "action_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 144,
        "action": "pause"
    }
}

Response

{
    "code": 0
}

Restart a campaign.

Request

Response

Request

{
    "request": "action_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 144,
        "action": "restart"
    }
}

Response

{
    "code": 0
}

Request: query_participants

Retrieve participants for an OTA campaign

Requests

Responses

Errors

Requests

This request has multiple formats in which it can be sent:

{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign."
    }
}
{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign.",
        "limit": "Number of participants to return",
        "offset": "The starting point to return participants from a campaign"
    }
}
{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign.",
        "limit": "Number of participants to return",
        "offset": "The starting point to return participants from a campaign",
        "state": "pending_build/pending_send/failed/finished. Return participants from a campaign after state."
    }
}

Responses

Response has multiple formats depending on the sent request:

{
    "code": 0,
    "count": "Number of participants from an OTA campaign."
}
{
    "code": 0,
    "participants": [
        {
            "participant_id": "ID of the participant",
            "imsi": "International Mobile Subscriber Identity",
            "msisdn": "Phone number.",
            "state": "Participant status",
            "participants": "Number of participants defined in campaign.",
            "error": "Error described if status is failed."
        }
    ]
}
{
    "code": 0,
    "participants": [
        {
            "participant_id": "ID of the participant",
            "imsi": "International Mobile Subscriber Identity",
            "msisdn": "Phone number.",
            "state": "Participant status set in request.",
            "participants": "Number of participants defined in campaign.",
            "error": "Error described if status is failed."
        }
    ]
}

Errors

{
    "code": 402,
    "message": "Missing all parameters."
}

Examples: query_participants

Retrieve number of participants set in a campaign.

Request

Response

Request

{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": "176"
    }
}

Response

{
    "code": 0,
    "count": 1
}

Retrieve a limited number of participants set in a campaign using parameters limit and offset.

Request

Response

Request

{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": 167,
        "offset": 0,
        "limit": 20
    }
}

Response

{
    "code": 0,
    "participants": [
        {
            "participant_id": 186,
            "imsi": "001010000010991",
            "msisdn": "963888810991",
            "state": "finished",
            "error": null
        }
    ]
}

Retrieve participants set in a campaign by specifying status.

Request

Response

Request

{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": 167,
        "offset": 0,
        "limit": 20,
        "state": "finished"
    }
}

Response

{
    "code": 0,
    "participants": [
        {
            "participant_id": 186,
            "imsi": "001010000010991",
            "msisdn": "963888810991",
            "state": "finished",
            "error": null
        }
    ]
}

Request: action_participant

Change participant status for an OTA campaign

Requests

Responses

Errors

Requests

{
    "request": "action_participant",
    "node": "ota",
    "params": {
        "participant_id": "Id of the participant.",
        "action": "cancel/hurry/retry. Action is based on participant status."
    }
}

Responses

{
    "code": 0
}

Errors

{
    "code": 402,
    "message": "Missing all parameters."
}
{
    "code": 402,
    "message": "Missing required 'campaign_id' field."
}
{
    "code": 402,
    "message": "Missing required 'action' field."
}
{
    "code": 401,
    "message": "Can't hurry failed SMS. Use retry option."
}

Examples: action_participant

Hurry a pending message.

Request

Response

Request

{
    "request": "action_participant",
    "node": "ota",
    "params": {
        "participant_id": "Id of the participant.",
        "action": "hurry",
        "comment__action": "Messages that have status failed/waiting_por can not be hurried."
    }
}

Response

{
    "code": 0
}

Retry to send a message.

Request

Response

Request

{
    "request": "action_participant",
    "node": "ota",
    "params": {
        "participant_id": "195",
        "action": "retry"
    }
}

Response

{
    "code": 0
}

Cancel sending a message.

Request

Response

Request

{
    "request": "action_participant",
    "node": "ota",
    "params": {
        "participant_id": "195",
        "action": "cancel"
    }
}

Response

{
    "code": 0
}

Request: trace

Trace participants from an OTA campaign.
Parameter campaign_id is mandatory.
One of the following parameters must pe specified: participant_id/msisdn/imsi

Requests

Responses

Errors

Requests

{
    "request": "trace",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign. Mandatory Parameter",
        "participant_id": "Id of the participant. Optional Parameter.",
        "msisdn": "Phone Number.  Optional Parameter",
        "imsi": "IMSI.  Optional Parameter"
    }
}

Responses

{
    "code": 0,
    "trace": {
        "participant": {
            "participant_id": "Id of the participant",
            "campaign_id": "Id of the campaign",
            "imsi": "IMSI",
            "msisdn": "MSISDN",
            "state": "State of the participant",
            "kic": "Key Identifier for ciphering. Used for encryption",
            "kid": "Key Identifier for RC/CC/DS. Used to verify integrity data.",
            "counter": "Counter used for replay detection and sequence integrity.",
            "cla": "Class Byte.",
            "spi": "Security Parameter Indicator.",
            "kic_alg": "Key and algorithm Identifier for ciphering. Algorithm type used for encryption.",
            "kid_alg": "Key and algorithm Identifier for RC/CC/DS. Algorithm type used to  compute RC/CC/DS field to verify integrity data.",
            "tar_ram": "Toolkit Application Reference for RAM.",
            "tar_rfm_sim": "Toolkit Application Reference for RFM SIM",
            "tar_rfm_usim": "Toolkit Application Reference for RFM USIM"
        },
        "messages": [
            {
                "message_id": "Id of the message.",
                "campaign_id": "Id of the campaign",
                "participant_id": "Id of the participant",
                "state": "State of the message",
                "tpdu": "Transport Protocol Data Unit",
                "msisdn": "MSISDN",
                "originator": "Source number",
                "ud": "User Data",
                "operation": "Operation",
                "por": "Proof of Request",
                "por_status": "PoR Decoded",
                "last_error": "Last error occurred.",
                "tries": "Attempts to send message",
                "next_try": "Date and time when the message will be retried.",
                "expires": "Date and time when message will be marked as failed.",
                "submitted": "Date and time when message was sent."
            }
        ]
    }
}

Errors

{
    "code": 402,
    "message": "Please specify imsi/msisdn for trace"
}
{
    "code": 402,
    "message": "Missing required campaign_id/participant_id field"
}

Examples: trace

Trace a participant from a campaign by specifying participant_id.

Request

Response

Request

{
    "request": "trace",
    "node": "ota",
    "params": {
        "campaign_id": "142",
        "participant_id": "161"
    }
}

Response

{
    "code": 0,
    "trace": {
        "participant": {
            "participant_id": 161,
            "campaign_id": 142,
            "imsi": "001010000010991",
            "msisdn": "963888810991",
            "state": "pending_send",
            "kic": "86ADE6DAF787FF199ACB51FFA118F765",
            "kid": "D6490DCB0EC849A66E43A455916D7DC0",
            "counter": "0000000070",
            "cla": "80",
            "spi": "1621",
            "kic_alg": "15",
            "kid_alg": "15",
            "tar_ram": "000000",
            "tar_rfm_sim": "b00010",
            "tar_rfm_usim": "b00001"
        },
        "messages": [
            {
                "message_id": 615,
                "campaign_id": 142,
                "participant_id": 161,
                "state": "pending",
                "tpdu": null,
                "msisdn": "963888810991",
                "originator": "963880099",
                "ud": "02700000601516211515B000106298D8459514F188A229D099FA9D4F5C2E39C29643A96A26867022AF0F8FFB5681A3D96DC109D3175D2D7BE93E335FA12E10BF131FA2230D7B5EB97A3E41C0EF356BF2BAD01A695208F2D32F7FD23098AC291DB85DC2A13C",
                "operation": "rfm",
                "por": null,
                "por_status": null,
                "last_error": null,
                "tries": 3,
                "next_try": "2019-10-15 12:01:51",
                "expires": "2019-10-29 11:01:51",
                "submitted": "2019-10-15 12:01:51"
            }
        ]
    }
}

Request: query_stats

Retrieve statistics from a running node.
More information about this request here

This documentation was generated on 10 December 2023

YateOTA – JSON API for Control & Stats

Request: query_campaigns

Request: action_campaign

Request: query_participants

Request: action_participant

Request: trace

Request: query_stats