Grovoice API
Back to Home

Contents

API Documentation

This document describes how to use the Grovoice API for third-party integration with our voice call system.

Base URL

All API endpoints use the following base URL, which is set in your Laravel .env as APP_URL:

https://voice.sacloud.site

Example endpoint: https://voice.sacloud.site/api/templates

Authentication

All API requests require an API token. These tokens can be generated by system administrators for third-party clients.

Token Format

API tokens should be included in the HTTP Authorization header as Bearer tokens:

Authorization: Bearer YOUR_API_TOKEN

Voice Templates

Templates are text content with variables that can be used for voice calls.

GET /api/templates

Returns a list of all voice templates for the authenticated user.

cURL Example:

curl --request GET "https://voice.sacloud.site/api/templates" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Response Example:

{
  "templates": [
    {
      "id": 1,
      "name": "Appointment Reminder",
      "language": "en-US",
      "variables": ["name", "time", "date"],
      "created_at": "2023-04-10T12:00:00Z",
      "updated_at": "2023-04-10T12:00:00Z"
    },
    {
      "id": 2,
      "name": "Welcome Message",
      "language": "en-US",
      "variables": ["name", "company"],
      "created_at": "2023-04-10T12:30:00Z",
      "updated_at": "2023-04-10T12:30:00Z"
    }
  ]
}
GET /api/templates/{id}

Returns detailed information about a specific voice template.

cURL Example:

curl --request GET "https://voice.sacloud.site/api/templates/1" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Parameters:

Name Type Description
id integer The ID of the template

Response Example:

{
  "template": {
    "id": 1,
    "name": "Appointment Reminder",
    "content": "Hello {{ name }}, this is a reminder that your appointment is scheduled for {{ time }} on {{ date }}. Please call us if you need to reschedule.",
    "language": "en-US",
    "variables": ["name", "time", "date"],
    "user_id": 1,
    "created_at": "2023-04-10T12:00:00Z",
    "updated_at": "2023-04-10T12:00:00Z"
  }
}

Voice Schedules

Schedules determine when and how voice templates are used to make calls.

GET /api/schedules

Returns a list of all voice call schedules for the authenticated user.

cURL Example:

curl --request GET "https://voice.sacloud.site/api/schedules" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Response Example:

{
  "schedules": [
    {
      "id": 1,
      "template_id": 1,
      "phone_number": "+15551234567",
      "frequency": "daily",
      "start_date": "2023-04-15",
      "end_date": "2023-05-15",
      "status": "active",
      "variable_values": {
        "name": "John Smith",
        "time": "2:30 PM",
        "date": "Monday"
      },
      "template": {
        "id": 1,
        "name": "Appointment Reminder",
        "language": "en-US"
      },
      "created_at": "2023-04-10T14:00:00Z",
      "updated_at": "2023-04-10T14:00:00Z"
    }
  ]
}
GET /api/schedules/{id}

Returns detailed information about a specific voice call schedule.

cURL Example:

curl --request GET "https://voice.sacloud.site/api/schedules/1" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Parameters:

Name Type Description
id integer The ID of the schedule

Response Example:

{
  "schedule": {
    "id": 1,
    "user_id": 1,
    "template_id": 1,
    "phone_number": "+15551234567",
    "frequency": "daily",
    "start_date": "2023-04-15",
    "end_date": "2023-05-15",
    "status": "active",
    "variable_values": {
      "name": "John Smith",
      "time": "2:30 PM",
      "date": "Monday"
    },
    "template": {
      "id": 1,
      "name": "Appointment Reminder",
      "content": "Hello {{ name }}, this is a reminder that your appointment is scheduled for {{ time }} on {{ date }}. Please call us if you need to reschedule.",
      "language": "en-US",
      "variables": ["name", "time", "date"]
    },
    "created_at": "2023-04-10T14:00:00Z",
    "updated_at": "2023-04-10T14:00:00Z"
  }
}
POST /api/schedules

Creates a new voice call schedule.

cURL Example:

curl --request POST "https://voice.sacloud.site/api/schedules" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "template_id": 1,
    "phone_number": "+15551234567",
    "variable_values": {
      "name": "John Smith",
      "time": "2:30 PM",
      "date": "Monday"
    },
    "frequency": "daily",
    "start_date": "2023-04-15",
    "end_date": "2023-05-15",
    "status": "active"
  }'

Request Parameters:

Name Type Required Description
template_id integer Yes The ID of the template to use
phone_number string Yes The phone number to call
variable_values object Yes Object with key-value pairs for template variables
frequency string Yes Call frequency: every_2_minutes, every_5_minutes, every_10_minutes, every_30_minutes, hourly, once, daily, weekly, or monthly
start_date date Yes Date to start the call schedule (YYYY-MM-DD)
end_date date No Date to end the call schedule (YYYY-MM-DD)
status string Yes Initial status: active, paused, or completed

Request Example:

{
  "template_id": 1,
  "phone_number": "+15551234567",
  "variable_values": {
    "name": "John Smith",
    "time": "2:30 PM",
    "date": "Monday"
  },
  "frequency": "daily",
  "start_date": "2023-04-15",
  "end_date": "2023-05-15",
  "status": "active"
}

Response Example:

{
  "message": "Schedule created successfully",
  "schedule": {
    "id": 1,
    "user_id": 1,
    "template_id": 1,
    "phone_number": "+15551234567",
    "frequency": "daily",
    "start_date": "2023-04-15",
    "end_date": "2023-05-15",
    "status": "active",
    "variable_values": {
      "name": "John Smith",
      "time": "2:30 PM",
      "date": "Monday"
    },
    "created_at": "2023-04-10T14:00:00Z",
    "updated_at": "2023-04-10T14:00:00Z"
  }
}
POST /api/schedules/{id}/status

Updates the status of a voice call schedule.

Parameters:

Name Type Description
id integer The ID of the schedule to update

Request Parameters:

Name Type Required Description
status string Yes New status: active, paused, or completed

Request Example:

{
  "status": "paused"
}

Response Example:

{
  "message": "Schedule status updated successfully",
  "schedule": {
    "id": 1,
    "status": "paused",
    "updated_at": "2023-04-10T15:30:00Z"
  }
}
POST /api/voice-logs

Retrieves paginated voice logs for a given schedule.

Request Parameters:

Name Type Required Description
schedule_id integer Yes The ID of the voice schedule
per_page integer No Number of logs per page (default: 10)
current_page integer No Current page number (default: 1)

Response Example:

{
 "voice_logs": {
  "current_page": 1,
   "data": [
     {
       "id": 1,
       "voice_schedule_id": 1,
       "report": "Sent",
       "created_at": "2023-04-10T15:30:00Z",
       "updated_at": "2023-04-10T15:30:00Z"
     },
      ...
    ],
    "first_page_url": "...",
    "from": 1,
    "last_page": 5,
    "last_page_url": "...",
    "links": [...],
    "next_page_url": "...",
    "path": "...",
    "per_page": 10,
    "prev_page_url": null,
    "to": 10,
    "total": 50
 }
}
POST /api/total-voice-logs

Retrieves the total number of voice logs and answered voice logs for a given schedule.

Query Parameters:

Name Type Required Description
schedule_id integer Yes The ID of the voice schedule

Response Example:

{
"total_calls": 100,
"total_answered": 75
}
GET /api/user

Retrieves information about the authenticated user.

Parameters:

Name Type Required Description
Authorization string Yes Bearer token in the Authorization header

Response Example:

{
"user": {
 "id": 1,
 "name": "John Doe",
 "email": "john.doe@example.com",
 "balance": 100.50,
 "created_at": "2023-04-10T15:30:00Z",
 "updated_at": "2023-04-10T15:30:00Z"
 }
}

Error Handling

The API returns standard HTTP status codes:

Status Code Description
200Success
201Resource created
400Bad request
401Unauthorized (invalid or missing token)
403Forbidden (token doesn't have required abilities)
404Resource not found
422Validation error
500Server error

Error Response Format

Error responses will include a message field explaining the error:

{
  "message": "The requested resource was not found"
}

For validation errors, the response will include a list of errors:

{
  "errors": {
    "template_id": ["The template id field is required"],
    "status": ["The status must be one of: active, paused, completed"]
  }
}