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:

http://grovoice.com

Example endpoint: http://grovoice.com/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 "http://grovoice.com/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 "http://grovoice.com/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 "http://grovoice.com/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 "http://grovoice.com/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 "http://grovoice.com/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
200	Success
201	Resource created
400	Bad request
401	Unauthorized (invalid or missing token)
403	Forbidden (token doesn't have required abilities)
404	Resource not found
422	Validation error
500	Server 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"]
  }
}

Contents

API Documentation

Base URL

Authentication

Token Format

Voice Templates

cURL Example:

Response Example:

cURL Example:

Parameters:

Response Example:

Voice Schedules

cURL Example:

Response Example:

cURL Example:

Parameters:

Response Example:

cURL Example:

Request Parameters:

Request Example:

Response Example:

Parameters:

Request Parameters:

Request Example:

Response Example:

Request Parameters:

Response Example:

Query Parameters:

Response Example:

Parameters:

Response Example:

Error Handling

Error Response Format