Customer Visits and Calendar Integration
Customer Visit lets representatives plan customer appointments in their Staff workspace. A visit can be onsite, remote, by phone or another type, with a start and end time, address, notes, outcome, follow-up date and optional related order.
Customers can receive visit details by email, confirm or cancel through a time-limited link, and see upcoming and recent visits in their account dashboard. Representatives can download calendar files and synchronize visits to Google Calendar or Microsoft 365.
Install
composer require mageb2b/staff-customervisit:*
php bin/magento module:enable MageB2B_StaffCustomerVisit
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush
Magento Admin users manage visits under Staff > Staff Visits. The staff account form also gains a Visits tab listing that representative's visits. Staff users work with visits and their calendar from the storefront Staff area.
Plan a visit
- Open a customer that is assigned to the representative.
- Create a visit and choose the type, start and end time, and customer address where relevant.
- Add a clear title and only the notes the customer should be allowed to receive.
- Decide whether to inform the customer or request confirmation.
- Save the visit and check its calendar entry.
- After the appointment, record the outcome, mark the appropriate status and schedule a next visit if needed.
The storefront visit form offers five states: planned, confirmed, done, cancelled and no-show. The Magento Admin visit form and the Default visit status setting only cover planned, confirmed and cancelled — done and no-show are outcome states that representatives record in the Staff workspace after the appointment. The default is planned; the default type is onsite.
Day route
The Staff calendar includes an Open day route action that redirects to a Google Maps directions URL for the representative's visits on the current day. The device's current location is the starting point and each visit's customer address becomes a waypoint in start-time order. Visits without a customer address are skipped; the action reports an error when no routable visit exists for the day.
Customer links and calendar files
Confirmation/cancellation links and ICS download links use separate expiring tokens. Both expire after 30 days by default. Changing the expiry affects newly created links; it does not make an old, expired link reusable.
Treat these URLs as private. Do not paste them into public tickets or analytics events. If a customer reports an expired link, update and resend the visit rather than extending the token manually.
Visit settings
Under Stores > Configuration > MageB2B > Staff > Visit Settings:
| Setting | Default | Effect |
|---|---|---|
| Allow inform customer | Yes | Enables visit-detail emails |
| Allow accept invitation | Yes | Enables customer confirmation links |
| Default visit status | Planned | Initial state for new visits |
| Default visit type | Onsite | Initial appointment type |
| Closest visits days range | 30 | Look-ahead period for the closest-visits list |
| ICS token expiry | 30 days | Lifetime of calendar-download links |
| Customer action link expiry | 30 days | Lifetime of confirm/cancel links |
| Show upcoming visits in customer dashboard | Yes | Adds the upcoming block to customer accounts |
| Show recent visits in customer dashboard | Yes | Adds the recent block to customer accounts |
| Show weekend days in calendar | Yes | Includes locale-defined weekend days |
The reminder cron job runs daily at 06:00 and emails the customer a reminder for every visit starting the next day that is not marked visited and not cancelled. The message carries a fresh ICS download link and confirm/cancel action links; the confirm link is only included while the visit is not yet approved. Magento cron must be running for scheduled reminders.
External calendar synchronization
Enable synchronization under Calendar Integration, then select one provider.
For Google, configure the OAuth client ID and secret, the exact callback URL and a default calendar ID such as primary. For Microsoft, configure the application ID, secret, tenant ID, exact callback URL and calendar owner user principal name or GUID.
Each representative connects their own calendar from the Staff calendar settings. Provider credentials are stored encrypted in Magento configuration, while the per-Staff OAuth record identifies the provider and selected calendar.
Before rollout:
- Register the exact HTTPS redirect URI shown by the store with the provider.
- Grant only the calendar permissions required by the integration.
- Connect one representative in staging.
- Create, move and cancel a visit and confirm that the external event follows each change.
- Revoke the connection and verify the Staff UI reports the disconnected state cleanly.
Email templates
The add-on supplies templates for visit creation, updates, cancellation, reminders, customer cancellation, information and approval. They must also be selected in Stores > Configuration > MageB2B > Staff > Email settings > Activated Emails. If a visit saves but no email arrives, check that allowlist before changing SMTP settings.
Troubleshooting
- Customer cannot confirm: check the link expiry and whether invitation acceptance is enabled.
- ICS download fails: create a fresh visit link and verify the store base URL is reachable externally.
- External event is missing: check synchronization is enabled, the representative completed OAuth, and the selected calendar still exists.
- Reminder is late: confirm Magento cron ran at 06:00 in the store's server time zone.
- Wrong times appear: compare Magento locale/time-zone configuration, the representative's calendar zone and the customer-facing email.
Related: Customer History and Field Sales Teams.