Audio Caller

LINE Planet provides the Audio Caller feature that allows your app server to request an audio call directly to the Planet Cloud. You can use this feature to make an automated call on the server side for your own use case, such as playing audio files with pre-recorded messages for your customer.

Note

For the Audio Caller feature, you can only use the audio files uploaded through LINE Planet Console in advance. For more information, refer to the LINE Planet Console guide.

For the Audio Caller feature, the following server APIs are used in addition to the existing APIs.

• Make Agent 1-to-1 Call API
• Agent Call Status callback

The following diagram shows the sequence for the Audio Caller feature.

1. Your app server makes a request to Planet Cloud to initiate Audio Caller using the Make Agent 1-to-1 Call API.
2. Planet Cloud notifies your app server of the incoming call using the Notify callback.
3. Your app server sends a push notification to your app client.
4. Planet Cloud invokes the Agent Call Status callback to notify your app server of the status of the Audio Caller.

Make Agent 1-to-1 Call API

This API allows your app server to initiate Audio Caller.

Access information

Environment	Base URL
Evaluation	https://vpnx-stn-api.line-apps-rc.com

Method and endpoint

• Method: POST
• Endpoint

  /tas/v2/agt_call/audio_caller/{to-serviceId}/{to-userId}

Headers

• Authorization: Basic {credentials}
• Accept: application/json
• Content-Type: application/json

Path parameters

Parameter	Description
to-serviceId	Service ID of the callee's service
to-userId	User ID of the callee

Request body

Parameter	Type	Required	Limit	Default value	Description
requestContext	AgentCallRequestContext object	Y			Context of the Audio Caller request
mediaSourceType	String	Y	UTF-8 48 bytes		Type of the audio source STORED_SOURCE
storedSource	StoredAudioSourceInfo object	Y			Media source information
appSvrData	String	N	UTF-8 4095 bytes	NULL	App server data
callStartMessage	String	N	UTF-8 199 bytes	NULL	Call start message
recordOnCloud	Boolean	N		false	This parameter is used to inform the callee about the caller's cloud recording setting, and it is delivered via cc_param. If recordOnCloud is null, it is not included in cc_param.
useResponderPreparation	Boolean	N		false	Whether to use responder preparation status

AgentCallRequestContext object

Property	Type	Required	Description
userId	String	Y	User ID of the caller
serviceId	String	Y	Service ID of the caller

StoredAudioSourceInfo object

Property	Type	Required	Limit	Default value	Description
storedAudioSources	ObjectList	Y			Information of the stored audio sources. You can set information of one or more audio sources to play. If there are more than one audio sources, they are played in sequential order. The maximum number of audio sources is 5.
storedAudioSources > contentId	String	Y	Fixed length 12-character hex string		ID of the audio source, which is issued when you upload an audio file to LINE Planet Console
playCount	Int	N	1–3	2	Number of times to repeat the sequential playback of all the audio sources
playWaitTime	Int	N	1000–4000	1000	Duration between the call connection and the start of the media playback, in milliseconds

Response

Property	Type	Nullable	Limit	Description
sid	String	N	Fixed length 36 bytes	Call session ID e.g., a30dc565-0c71-420a-9752-84eb43f8645c

Example

curl --location --request POST 'https://vpnx-stn-api.line-apps-rc.com/tas/v2/agt_call/audio_caller/${service-id}/${user-id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ${credentials}' \
--data '{
    "requestContext": {
        "userId": "${user-id}",
        "serviceId": "${service-id}"
    },
    "mediaSourceType": "STORED_SOURCE",
    "storedSource": {
        "storedAudioSources": [
            {
                "contentId": "5498f04048fa"
            },
            {
                "contentId": "c17d343002a9"
            }
        ],
        "playWaitTime": 1500,
        "playCount": 2
    },
    "recordOnCloud": false,
    "useResponderPreparation": false
}'
 
 
{
    "status": "success",
    "data": {
        "sid": "2b53fe1d-5057-4265-ad76-96b2fc6f4961"
    },
    "timestamp": 1743055021284
}

Agent Call Status callback

The Agent Call Status callback is always invoked when a successful response is received from the agent call API request. This callback indicates whether the server has successfully initiated the call (WAITANSWER) to the callee.

For call events after WAITANSWER, such as the callee accepting the call or rejecting the call, refer to 1-to-1 Call Event Callback with the sid value.

Method and endpoint

• Method: GET
• Endpoint: ${agent_call_status_cb_url}

Query parameters

Key	Type	Nullable	Description	Example
sid	String	N	Session ID. You can identify a call using an sid. Fixed 36 bytes size without null.	6364e8b3-bdac-436e-9631-0bce2498ce0c
agent_type	String	N	Agent Type AUDIO_CALLER	AUDIO_CALLER
media_source_type	String	N	The media type of the agent call STORED_SOURCE	STORED_SOURCE
result	String	N	Result of making an agent call SUCCESS FAIL	SUCCESS
fail_reason	String	N	Reason for a failure (If successful, None)	Invalid peerId

Example

# Let's suppose agent_call_status_cb_url is
# http://sample.server.com:20200/audio_caller_event
# LINE Planet server will send a request to agent_call_status_cb_url as follows.

GET http://sample.server.com:20200/audio_caller_event?
sid=6364e8b3-bdac-436e-9631-0bce2498ce0c&
agent_type=AUDIO_CALLER&
media_source_type=STORED_SOURCE&
result=Success&
fail_reason=None