openapi: 3.0.4 info: title: Evolution Foundation - CRM Service - Scheduled Actions description: Management of contacts, conversations, inboxes, labels and macros version: 1.1.0 servers: - url: https://api.evoai.app description: Production server - url: http://localhost:3000 description: Development server variables: port: default: '3000' - url: '{customUrl}' description: Custom server variables: customUrl: default: https://your-instance.com description: Enter your server URL paths: /api/v1/scheduled_actions: get: summary: List scheduled actions description: 'Returns paginated and filtered list of scheduled actions. Supports filters by status, action type, period, deal, contact and conversation. ' operationId: listScheduledActions security: - userApiKey: [] parameters: - name: page in: query description: Page number schema: type: integer default: 1 minimum: 1 - name: per_page in: query description: Items per page schema: type: integer default: 20 minimum: 1 maximum: 100 - name: status in: query description: Filter by status schema: type: string enum: - scheduled - executing - completed - failed - cancelled - name: action_type in: query description: Filter by action type schema: type: string enum: - send_message - send_email - execute_webhook - trigger_journey - create_task - update_deal_stage - add_deal_note - send_whatsapp - send_sms - name: deal_id in: query description: Filter by deal ID schema: type: integer - name: contact_id in: query description: Filter by contact ID schema: type: string format: uuid - name: conversation_id in: query description: Filter by conversation ID schema: type: string format: uuid - name: scheduled_from in: query description: Start date of scheduling (ISO 8601) schema: type: string format: date-time - name: scheduled_to in: query description: End date of scheduling (ISO 8601) schema: type: string format: date-time - name: sort in: query description: Sorting (recent = most recent, default = by scheduled time) schema: type: string enum: - recent - scheduled_time default: scheduled_time responses: '200': description: List of scheduled actions returned successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array items: $ref: '#/components/schemas/ScheduledAction' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' pagination: type: object properties: page: type: integer example: 1 pageSize: type: integer example: 20 total: type: integer example: 42 totalPages: type: integer example: 3 hasNextPage: type: boolean example: true hasPreviousPage: type: boolean example: false message: type: string example: Scheduled actions retrieved successfully examples: success: value: success: true data: [] meta: timestamp: '2024-01-15T10:30:00Z' pagination: page: 1 pageSize: 20 total: 42 totalPages: 3 hasNextPage: true hasPreviousPage: false message: Scheduled actions retrieved successfully '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: GET '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: GET '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: You do not have permission to access scheduled actions meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: GET '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: GET '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: GET post: summary: Create scheduled action description: Schedules a new action to be executed at a specific time operationId: createScheduledAction security: - userApiKey: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScheduledActionInput' responses: '200': description: Scheduled action created successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: $ref: '#/components/schemas/ScheduledAction' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string example: Scheduled action created successfully examples: success: value: success: true data: id: dd0e8400-e29b-41d4-a716-446655440008 action_type: send_message status: scheduled scheduled_at: '2024-01-20T14:00:00Z' payload: {} created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Scheduled action created successfully '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid request data meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: POST '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: POST '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: You do not have permission to create scheduled actions meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: POST '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: POST '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: VALIDATION_ERROR message: Validation failed details: scheduled_for: - is required action_type: - is required meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: POST '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions method: POST /api/v1/scheduled_actions/by_contact/{contact_id}: get: summary: List scheduled actions of a contact description: Returns all scheduled actions linked to a specific contact operationId: listScheduledActionsByContact security: - userApiKey: [] parameters: - name: contact_id in: path required: true description: ID do contato (UUID) schema: type: string format: uuid - name: page in: query schema: type: integer default: 1 - name: per_page in: query schema: type: integer default: 20 responses: '200': description: Scheduled actions list retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array items: $ref: '#/components/schemas/ScheduledAction' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' pagination: type: object properties: page: type: integer example: 1 pageSize: type: integer example: 20 total: type: integer example: 3 totalPages: type: integer example: 1 hasNextPage: type: boolean example: false hasPreviousPage: type: boolean example: false message: type: string example: Scheduled actions retrieved successfully examples: success: value: success: true data: [] meta: timestamp: '2024-01-15T10:30:00Z' pagination: page: 1 pageSize: 20 total: 3 totalPages: 1 hasNextPage: false hasPreviousPage: false message: Scheduled actions retrieved successfully '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid contact ID format meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/by_contact/{contact_id} method: GET '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/by_contact/{contact_id} method: GET '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: You do not have permission to access scheduled actions for this contact meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/by_contact/{contact_id} method: GET '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Contact not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/by_contact/{contact_id} method: GET '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/by_contact/{contact_id} method: GET /api/v1/scheduled_actions/by_deal/{deal_id}: get: summary: List scheduled actions for a deal description: Returns all scheduled actions linked to a specific deal operationId: listScheduledActionsByDeal security: - userApiKey: [] parameters: - name: deal_id in: path required: true description: ID do deal (pipeline item) schema: type: string format: uuid - name: page in: query schema: type: integer default: 1 - name: per_page in: query schema: type: integer default: 20 responses: '200': description: Scheduled actions list retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array items: $ref: '#/components/schemas/ScheduledAction' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' pagination: type: object properties: page: type: integer example: 1 pageSize: type: integer example: 20 total: type: integer example: 5 totalPages: type: integer example: 1 hasNextPage: type: boolean example: false hasPreviousPage: type: boolean example: false message: type: string example: Scheduled actions retrieved successfully examples: success: value: success: true data: [] meta: timestamp: '2024-01-15T10:30:00Z' pagination: page: 1 pageSize: 20 total: 5 totalPages: 1 hasNextPage: false hasPreviousPage: false message: Scheduled actions retrieved successfully '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid deal ID format meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/by_deal/{deal_id} method: GET '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/by_deal/{deal_id} method: GET '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: You do not have permission to access scheduled actions for this deal meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/by_deal/{deal_id} method: GET '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Deal not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/by_deal/{deal_id} method: GET '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/by_deal/{deal_id} method: GET /api/v1/scheduled_actions/{id}: parameters: - name: id in: path required: true description: Scheduled action ID schema: type: string format: uuid get: summary: Get scheduled action details description: Returns complete information of a specific scheduled action operationId: getScheduledAction security: - userApiKey: [] responses: '200': description: Scheduled action retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: $ref: '#/components/schemas/ScheduledAction' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string example: Scheduled action retrieved successfully examples: success: value: success: true data: id: dd0e8400-e29b-41d4-a716-446655440008 action_type: send_message status: scheduled scheduled_at: '2024-01-20T14:00:00Z' payload: {} created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Scheduled action retrieved successfully '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid scheduled action ID format meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: GET '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: GET '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: You do not have permission to access this scheduled action meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: GET '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Scheduled action not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: GET '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: GET patch: summary: Update scheduled action description: 'Updates properties of a scheduled action (only for actions with ''scheduled'' status). Allows changing time, payload and recurrence settings. ' operationId: updateScheduledAction security: - userApiKey: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScheduledActionUpdate' responses: '200': description: Scheduled action updated successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: $ref: '#/components/schemas/ScheduledAction' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string example: Scheduled action updated successfully examples: success: value: success: true data: id: dd0e8400-e29b-41d4-a716-446655440008 action_type: send_message status: scheduled scheduled_at: '2024-01-25T14:00:00Z' payload: {} created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:35:00Z' meta: timestamp: '2024-01-15T10:35:00Z' message: Scheduled action updated successfully '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Cannot update action that is not scheduled meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: PATCH '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: PATCH '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: You do not have permission to update this scheduled action meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: PATCH '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Scheduled action not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: PATCH '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: VALIDATION_ERROR message: Validation failed details: scheduled_for: - must be a future date meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: PATCH '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: PATCH delete: summary: Cancel scheduled action description: Marks the scheduled action as cancelled, preventing its execution operationId: cancelScheduledAction security: - userApiKey: [] responses: '200': description: Scheduled action cancelled successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object nullable: true example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string example: Scheduled action cancelled successfully examples: success: value: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Scheduled action cancelled successfully '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid scheduled action ID format meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: DELETE '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: DELETE '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: You do not have permission to cancel this scheduled action meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: DELETE '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Scheduled action not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: DELETE '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/scheduled_actions/{id} method: DELETE components: schemas: ErrorResponse: type: object required: - success - error - meta properties: success: type: boolean example: false error: type: object required: - code - message properties: code: type: string example: VALIDATION_ERROR message: type: string example: Validation failed details: type: object additionalProperties: true nullable: true meta: type: object required: - timestamp - path - method properties: timestamp: type: string format: date-time example: '2024-01-15T10:30:00Z' path: type: string example: /public/api/v1/inboxes/{inbox_identifier}/contacts method: type: string example: POST ScheduledAction: type: object properties: id: type: string format: uuid description: Unique scheduled action ID example: 550e8400-e29b-41d4-a716-446655440000 account_id: type: string format: uuid description: Account ID example: 123e4567-e89b-12d3-a456-426614174000 deal_id: type: string format: uuid nullable: true description: Linked deal ID (pipeline item) example: 550e8400-e29b-41d4-a716-446655440000 contact_id: type: string format: uuid nullable: true description: Linked contact ID example: 987e6543-e21b-12d3-a456-426614174111 conversation_id: type: string format: uuid nullable: true description: Linked conversation ID example: 111e2222-e33b-44d5-a666-777888999000 action_type: type: string description: Action type to be executed enum: - send_message - send_email - execute_webhook - trigger_journey - create_task - update_deal_stage - add_deal_note - send_whatsapp - send_sms example: send_whatsapp status: type: string description: Action status enum: - scheduled - executing - completed - failed - cancelled example: scheduled scheduled_for: type: string format: date-time description: Scheduled date/time for execution example: '2025-01-15T14:30:00Z' executed_at: type: string format: date-time nullable: true description: Actual execution date/time example: null payload: type: object description: Action data (varies by action_type) additionalProperties: true example: message: Hello! How can I help? phone: '+5574999999999' template_id: type: string format: uuid nullable: true description: Message template ID (if applicable) example: null created_by: type: string format: uuid description: Creator user ID example: 444e5555-e66b-77d8-a999-000111222333 retry_count: type: integer description: Number of execution attempts example: 0 max_retries: type: integer description: Maximum allowed attempts example: 3 error_message: type: string nullable: true description: Error message from last execution (if failed) example: null journey_session_id: type: string nullable: true description: Journey session ID (if linked) example: null recurrence_type: type: string nullable: true description: Recurrence type enum: - once - daily - weekly - monthly example: once recurrence_config: type: object nullable: true description: Recurrence settings additionalProperties: true example: null time_until_execution: type: integer description: Time in seconds until execution example: 86400 formatted_time_until: type: string description: Formatted time until execution example: 1d overdue: type: boolean description: Whether the action is overdue example: false can_retry: type: boolean description: Whether the action can be retried example: false creator: type: object nullable: true description: Creator user data properties: id: type: string format: uuid name: type: string email: type: string format: email example: id: 444e5555-e66b-77d8-a999-000111222333 name: John Doe email: john@example.com created_at: type: string format: date-time example: '2025-01-13T10:00:00Z' updated_at: type: string format: date-time example: '2025-01-13T10:00:00Z' ScheduledActionInput: type: object required: - scheduled_action properties: scheduled_action: type: object required: - action_type - scheduled_for - payload properties: deal_id: type: string format: uuid nullable: true description: Deal ID (requires at least one of deal_id, contact_id or conversation_id) example: 550e8400-e29b-41d4-a716-446655440000 contact_id: type: string format: uuid nullable: true description: Contact ID example: 987e6543-e21b-12d3-a456-426614174111 conversation_id: type: string format: uuid nullable: true description: Conversation ID example: 111e2222-e33b-44d5-a666-777888999000 action_type: type: string description: Action type enum: - send_message - send_email - execute_webhook - trigger_journey - create_task - update_deal_stage - add_deal_note - send_whatsapp - send_sms example: send_whatsapp scheduled_for: type: string format: date-time description: Date/time for execution (cannot be in the past) example: '2025-01-15T14:30:00Z' template_id: type: string format: uuid nullable: true description: Message template ID example: null max_retries: type: integer default: 3 description: Maximum retry attempts in case of failure example: 3 journey_session_id: type: string nullable: true description: Journey session ID example: null recurrence_type: type: string nullable: true enum: - once - daily - weekly - monthly default: once example: once payload: type: object description: Action-specific data additionalProperties: true example: message: 'Reminder: your meeting is tomorrow!' phone: '+5574999999999' recurrence_config: type: object nullable: true description: Recurrence settings (if recurrence_type != once) additionalProperties: true example: null ScheduledActionUpdate: type: object required: - scheduled_action properties: scheduled_action: type: object properties: scheduled_for: type: string format: date-time description: New date/time for execution example: '2025-01-16T10:00:00Z' max_retries: type: integer description: Update maximum retry attempts example: 5 payload: type: object description: Update action data additionalProperties: true recurrence_config: type: object description: Update recurrence settings additionalProperties: true securitySchemes: userApiKey: type: apiKey in: header name: api_access_token ApiAccessToken: type: apiKey in: header name: api_access_token description: API access token for user authentication